{ "openapi": "3.2.0", "info": { "title": "IRIS HTTP API", "version": "1", "description": "Canonical contract for the browser console BFF, internal management tier, device catalog, tracker, telemetry and artifact services. Guest Shell static files and staging path capabilities have dedicated access rules; other anonymous routes are limited to /healthz and /readyz." }, "tags": [ { "name": "console" }, { "name": "management" }, { "name": "catalog" }, { "name": "tracker" }, { "name": "telemetry" }, { "name": "artifact" } ], "x-iris-version-policy": { "current": "v1", "breakingChanges": "require a new major base path", "retirement": "announce for at least two dated releases; deprecated compatibility responses carry Deprecation and a dated Sunset" }, "x-iris-retained-v1-exceptions": { "trackerErrors": "BEP clients require bencoded failures, so tracker errors are not RFC 9457.", "probeErrors": "readyz 503 remains a deliberately non-disclosing {ok:false} health document.", "trackerTransport": "Port 6969 is HTTPS-only and uses the certificate pinned by device agents. IOx/XR agents use Bearer Authorization; Guest Shell uses query credentials. TLS protects both forms, and credentials are never logged.", "guestShellArtifacts": "IOS Guest Shell copy HTTPS uses five static files and four high-entropy staging filename forms. Staging files expire automatically. Explicit artifact API clients use resource-bound Basic authentication at /v1/devices/{device_id}/artifacts/{artifact_path}.", "resourcePaths": "Use the operation paths defined in this contract, including verb-based action paths.", "pagination": "Devices, audit, schedule occurrences and schedule receipts expose the documented paging shapes. Other collections are bounded by assignment or returned whole; they do not claim pagination.", "compareAndSet": "Schedules require a singleton strong If-Match or * on existing-row mutations (428 missing, 412 stale or raced). Peer policy exposes ETag/If-Match while accepting body if_revision through its Sunset. Device assignment uses expect_image_ids to compare the assigned set and returns the conflicting set when it differs.", "statusCodes": "Upsert and job operations return 200 with the documented response body. Operations declare a bounded set of error responses; conditional branches may use a subset.", "idempotency": "Only operations explicitly declaring Idempotency-Key have process-local 24-hour successful-response replay. Restart clears that replay ledger and in-memory jobs; inspect catalog state, deployment records, and persisted deployment logs before retrying." }, "paths": { "/api/v1/peer-policy": { "get": { "operationId": "console_get_api_v1_peer_policy", "summary": "Read peer policy", "description": "Read peer policy. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read peer policy response", "content": { "application/json": { "schema": { "title": "ConsolePeerPolicyResponse", "type": "object", "properties": { "schema": { "type": "integer" }, "revision": { "type": "integer" }, "degraded": { "type": "boolean" }, "fail_closed": { "type": "boolean" }, "quarantine": { "title": "ConsolePeerPolicyResponseQuarantine", "type": "object", "properties": { "reserved": { "type": "boolean" }, "description": { "type": "string" } }, "required": [ "reserved", "description" ], "additionalProperties": true }, "quarantine_assignments": { "type": "array", "items": { "type": "string" } }, "roles_supported": { "type": "boolean", "const": true }, "roles_present": { "type": "boolean" }, "roles": { "title": "ConsolePeerPolicyResponseRoles", "type": "object", "properties": { "defined": { "type": "integer" }, "restricted": { "type": "integer" }, "members": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "required": [ "defined", "restricted", "members" ], "additionalProperties": true }, "role_drift": { "title": "ConsolePeerPolicyResponseRole_Drift", "type": "object", "properties": { "count": { "type": "integer" }, "device_ids": { "type": "array", "items": { "type": "string" } }, "truncated": { "type": "boolean" } }, "required": [ "count", "device_ids", "truncated" ], "additionalProperties": true }, "outbox": { "title": "ConsolePeerPolicyResponseOutbox", "type": "object", "properties": { "unacknowledged": { "type": "integer" }, "capacity": { "type": "integer" } }, "required": [ "unacknowledged", "capacity" ], "additionalProperties": true }, "origin_qos": { "title": "ConsolePeerPolicyResponseOrigin_Qos", "type": "object", "properties": { "state": { "type": [ "string", "null" ] }, "global_option_count": { "type": "integer" }, "target_download_count": { "type": "integer" }, "applied_download_count": { "type": "integer" }, "last_reconciled_at": { "type": [ "number", "null" ] }, "last_error": { "type": [ "string", "null" ] } }, "required": [ "state", "global_option_count", "target_download_count", "applied_download_count", "last_reconciled_at", "last_error" ], "additionalProperties": true }, "fleet_rollup": { "type": "object", "properties": { "issued_revision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "applied": { "type": "object", "propertyNames": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])(?![\\s\\S])" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "description": "Agent-asserted accepted policy revisions as exact decimal string keys, mapped to inventory-device counts." }, "states": { "type": "object", "properties": { "applied": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "lkg": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "stale": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "rejected": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "tracker-only": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "pre-instructions": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "unknown": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "unavailable": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "pending": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "forbidden": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "floor_reset": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "none": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "revoked": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } }, "additionalProperties": false } }, "required": [ "issued_revision", "applied", "states" ], "additionalProperties": false }, "instruction_status": { "type": "object", "properties": { "observed_at": { "type": "number", "minimum": 0, "maximum": 9223372036854775807 }, "instr_stamp_missing": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "pointer_skew": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "issued_revision_label": { "type": [ "string", "null" ], "maxLength": 20, "pattern": "^r(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])(?![\\s\\S])" } }, "required": [ "observed_at", "instr_stamp_missing", "pointer_skew", "issued_revision_label" ], "additionalProperties": false }, "instruction_keys": { "oneOf": [ { "type": "object", "properties": { "schema": { "type": "string", "const": "iris-instruction-key-status/v1" }, "enabled": { "type": "boolean" }, "state": { "type": "string", "enum": [ "phase0", "ready", "renewal_due", "signing_refused", "keylist_missing", "invalid", "error" ] }, "certificate_days_to_expiry": { "type": [ "integer", "null" ], "minimum": -9223372036854775807, "maximum": 9223372036854775807 }, "certificate_renewal_due": { "type": "boolean" }, "signing_refused": { "type": "boolean" }, "keylist_seq": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9223372036854775807 }, "keylist_age_days": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "keylist_resign_due": { "type": "boolean" }, "roots_configured": { "type": "integer", "minimum": 0, "maximum": 2 }, "roots_attested_180d": { "type": "integer", "minimum": 0, "maximum": 2 }, "root_ceremony_overdue": { "type": "string", "enum": [ "unknown", "ok", "warn", "critical" ] }, "root_quorum_degraded": { "type": "boolean" }, "updated_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } }, "required": [ "schema", "enabled", "state", "certificate_days_to_expiry", "certificate_renewal_due", "signing_refused", "keylist_seq", "keylist_age_days", "keylist_resign_due", "roots_configured", "roots_attested_180d", "root_ceremony_overdue", "root_quorum_degraded", "updated_at" ], "additionalProperties": false }, { "type": "null" } ], "description": "Validated durable signing-custody status, or null when the status snapshot is absent, invalid, stale or unavailable." }, "enforcement": { "title": "ConsolePeerPolicyResponseEnforcement", "type": "object", "properties": { "state": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" }, "desired_ip_count": { "type": "integer" }, "conflict_count": { "type": "integer" }, "mutual_origin": { "title": "ConsolePeerPolicyResponseEnforcementMutual_Origin", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "preflight", "enforce" ] }, "newly_denied_device_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Prospective count in preflight mode only. Null means unavailable or requested enforce mode; use GET peer-policy/origin-enforcement for separately verified application evidence. Zero is a completed preflight with no newly denied devices." } }, "required": [ "mode", "newly_denied_device_count" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "mode": { "const": "enforce" } } }, "then": { "properties": { "newly_denied_device_count": { "const": null } } } } ] } }, "required": [ "state", "stale", "desired_ip_count", "conflict_count", "mutual_origin" ], "additionalProperties": true } }, "required": [ "schema", "revision", "degraded", "fail_closed", "quarantine", "quarantine_assignments", "roles_supported", "roles_present", "roles", "role_drift", "outbox", "origin_qos", "fleet_rollup", "instruction_status", "instruction_keys", "enforcement" ], "additionalProperties": true }, "example": { "schema": 1, "revision": 4, "degraded": false, "fail_closed": false, "quarantine": { "reserved": true, "description": "reserved policy value" }, "quarantine_assignments": [ "edge-02" ], "roles_supported": true, "roles_present": true, "roles": { "defined": 1, "restricted": 1, "members": { "boat": 2 } }, "role_drift": { "count": 0, "device_ids": [], "truncated": false }, "outbox": { "unacknowledged": 1, "capacity": 256 }, "origin_qos": { "state": null, "global_option_count": 0, "target_download_count": 0, "applied_download_count": 0, "last_reconciled_at": null, "last_error": null }, "fleet_rollup": { "issued_revision": 12, "applied": { "7": 1 }, "states": { "applied": 1 } }, "instruction_status": { "observed_at": 1788470400, "instr_stamp_missing": 0, "pointer_skew": 0, "issued_revision_label": "r12" }, "instruction_keys": { "schema": "iris-instruction-key-status/v1", "enabled": true, "state": "ready", "certificate_days_to_expiry": 14, "certificate_renewal_due": false, "signing_refused": false, "keylist_seq": 8, "keylist_age_days": 30, "keylist_resign_due": false, "roots_configured": 2, "roots_attested_180d": 2, "root_ceremony_overdue": "ok", "root_quorum_degraded": false, "updated_at": 1788470400 }, "enforcement": { "state": null, "stale": false, "desired_ip_count": 1, "conflict_count": 0, "mutual_origin": { "mode": "preflight", "newly_denied_device_count": null } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "400": { "description": "Invalid content length or Request body not supported", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Device status temporarily busy or Service unavailable or Management API unavailable", "x-iris-problem-codes": [ "projection-busy", "service-unavailable", "management-api-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "projection-busy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#projection-busy", "title": "Device status temporarily busy", "status": 503, "code": "projection-busy" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } }, "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/peer-policy/roles": { "get": { "operationId": "console_get_api_v1_peer_policy_roles", "summary": "List role definitions", "description": "List role definitions. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "List role definitions response", "content": { "application/json": { "schema": { "title": "ConsolePeerPolicyRolesResponse", "type": "object", "properties": { "revision": { "type": "integer" }, "degraded": { "type": "boolean" }, "fail_closed": { "type": "boolean" }, "roles": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,31}$", "not": { "enum": [ "default", "legacy", "origin", "quarantine", "seeder" ] } }, "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "restricted": { "type": "boolean" }, "origin": { "type": "boolean" }, "peers": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,31}$", "not": { "enum": [ "default", "legacy", "origin", "quarantine", "seeder" ] } }, "minItems": 1, "maxItems": 64, "uniqueItems": true, "x-iris-selfPeerRequired": true, "description": "Must contain the role's {name} path value; missing self returns 409 role_isolated." }, "nets": { "type": "array", "items": { "type": "string", "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])(?:/(?:(?=[0-9]{1,32}$(?![\\s\\S]))0*(?:[0-9]|[12][0-9]|3[0-2])|0\\.0\\.0\\.0|0\\.0\\.0\\.1|0\\.0\\.0\\.127|0\\.0\\.0\\.15|0\\.0\\.0\\.255|0\\.0\\.0\\.3|0\\.0\\.0\\.31|0\\.0\\.0\\.63|0\\.0\\.0\\.7|0\\.0\\.1\\.255|0\\.0\\.127\\.255|0\\.0\\.15\\.255|0\\.0\\.255\\.255|0\\.0\\.3\\.255|0\\.0\\.31\\.255|0\\.0\\.63\\.255|0\\.0\\.7\\.255|0\\.1\\.255\\.255|0\\.127\\.255\\.255|0\\.15\\.255\\.255|0\\.255\\.255\\.255|0\\.3\\.255\\.255|0\\.31\\.255\\.255|0\\.63\\.255\\.255|0\\.7\\.255\\.255|1\\.255\\.255\\.255|127\\.255\\.255\\.255|128\\.0\\.0\\.0|15\\.255\\.255\\.255|192\\.0\\.0\\.0|224\\.0\\.0\\.0|240\\.0\\.0\\.0|248\\.0\\.0\\.0|252\\.0\\.0\\.0|254\\.0\\.0\\.0|255\\.0\\.0\\.0|255\\.128\\.0\\.0|255\\.192\\.0\\.0|255\\.224\\.0\\.0|255\\.240\\.0\\.0|255\\.248\\.0\\.0|255\\.252\\.0\\.0|255\\.254\\.0\\.0|255\\.255\\.0\\.0|255\\.255\\.128\\.0|255\\.255\\.192\\.0|255\\.255\\.224\\.0|255\\.255\\.240\\.0|255\\.255\\.248\\.0|255\\.255\\.252\\.0|255\\.255\\.254\\.0|255\\.255\\.255\\.0|255\\.255\\.255\\.128|255\\.255\\.255\\.192|255\\.255\\.255\\.224|255\\.255\\.255\\.240|255\\.255\\.255\\.248|255\\.255\\.255\\.252|255\\.255\\.255\\.254|255\\.255\\.255\\.255|3\\.255\\.255\\.255|31\\.255\\.255\\.255|63\\.255\\.255\\.255|7\\.255\\.255\\.255))?$(?![\\s\\S])", "description": "IPv4 address, CIDR or dotted netmask/hostmask. A decimal prefix allows at most 32 digits, including leading zeroes; valid spelling is preserved." } }, "on_stale": { "type": "string", "enum": [ "keep", "defaults" ] }, "qos": { "type": "object", "properties": { "max_peers": { "type": "integer", "minimum": 1, "maximum": 1000 }, "per_peer_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "fanout": { "type": "integer", "minimum": 1, "maximum": 1000 }, "seed_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "seed_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "max_concurrent": { "type": "integer", "minimum": 1, "maximum": 1000 }, "catalog_tick_s": { "type": "integer", "minimum": 60, "maximum": 900, "multipleOf": 60 }, "telemetry_every_ticks": { "type": "integer", "minimum": 1, "maximum": 60 }, "telemetry_pause": { "type": "boolean" }, "request_peer_speed_limit_bps": { "type": "integer", "minimum": 0, "maximum": 1000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "announce_min_interval_s": { "type": "integer", "minimum": 10, "maximum": 300 }, "numwant": { "type": "integer", "minimum": 4, "maximum": 200 }, "handout_budget": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "additionalProperties": false, "description": "Replace this layer with any supported subset; an empty object clears it. Cross-field and restricted-role semantics are validated by the policy transaction." }, "qos_state": { "$ref": "#/components/schemas/TrackerQosStateMap" } } } }, "qos_state_default": { "$ref": "#/components/schemas/TrackerQosStateMap" } }, "required": [ "revision", "degraded", "fail_closed", "roles" ], "additionalProperties": true }, "example": { "revision": 4, "degraded": false, "fail_closed": false, "roles": { "boat": { "restricted": true, "peers": [ "boat" ], "origin": true } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "400": { "description": "Invalid content length or Request body not supported", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management api unavailable or Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } } } }, "/api/v1/peer-policy/roles/export-csv": { "get": { "operationId": "console_get_api_v1_peer_policy_roles_export_csv", "summary": "Export role definitions as CSV", "description": "Export role definitions as CSV. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. role definition batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "CSV document", "content": { "text/csv": { "schema": { "type": "string" }, "example": "role,restricted,peers,origin,nets,on_stale\nboat,true,boat;fiber,true,,keep\n" } } }, "400": { "description": "Invalid content length or Request body not supported", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management api unavailable or Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "x-iris-v1-resource-path-exception": "role definition batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API" } }, "/api/v1/peer-policy/roles/import-csv": { "post": { "operationId": "console_post_api_v1_peer_policy_roles_import_csv", "summary": "Replace role definitions from CSV", "description": "Replace role definitions from CSV. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. role definition batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "dry_run", "in": "query", "required": false, "description": "1 previews the locked candidate without persistence; 0 commits after required confirmation.", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "example": 1 }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong policy ETag. Missing: 428; stale: 412; race under the policy lock: 409. Confirmation is candidate-bound at threshold zero, including every changed QoS document.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Replace role definitions from CSV response", "content": { "application/json": { "schema": { "title": "ConsolePeerPolicyRolesImportCsvResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "candidate_revision": { "type": "integer" }, "dry_run": { "type": "boolean" }, "member_delta": { "type": "integer" }, "origin_access_lost": { "type": "integer" }, "empty_permitted_sets": { "type": "integer" }, "role_pairs_stopped": { "type": "integer" }, "qos_changed": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ] }, "roles": { "type": "integer" } }, "required": [ "ok", "revision", "candidate_revision", "dry_run", "member_delta", "origin_access_lost", "empty_permitted_sets", "role_pairs_stopped", "qos_changed", "requires_confirmation", "confirm_token", "roles" ], "additionalProperties": true }, "examples": { "confirmationRequired": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 1, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": true, "confirm_token": "candidate-bound-sha256", "roles": 2 } }, "noConfirmation": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": false, "confirm_token": null, "roles": 2 } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "400": { "description": "Invalid content length or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "409": { "description": "Operation backlog full or Revision conflict or Role in use or Role isolated or Role reserved name", "x-iris-problem-codes": [ "operation_backlog_full", "revision_conflict", "role_in_use", "role_isolated", "role_reserved_name" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "operation_backlog_full": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#operation_backlog_full", "title": "Operation backlog full", "status": 409, "code": "operation_backlog_full" } }, "revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#revision_conflict", "title": "Revision conflict", "status": 409, "code": "revision_conflict" } }, "role_in_use": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_in_use", "title": "Role in use", "status": 409, "code": "role_in_use" } }, "role_isolated": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_isolated", "title": "Role isolated", "status": 409, "code": "role_isolated" } }, "role_reserved_name": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_reserved_name", "title": "Role reserved name", "status": 409, "code": "role_reserved_name" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "422": { "description": "Invalid policy or Invalid policy request or Invalid roles csv", "x-iris-problem-codes": [ "invalid_policy", "invalid_policy_request", "invalid_roles_csv" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_policy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy", "title": "Invalid policy", "status": 422, "code": "invalid_policy" } }, "invalid_policy_request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } }, "invalid_roles_csv": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_roles_csv", "title": "Invalid roles csv", "status": 422, "code": "invalid_roles_csv" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Confirmation required or Precondition required", "x-iris-problem-codes": [ "confirmation_required", "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "confirmation_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#confirmation_required", "title": "Confirmation required", "status": 428, "code": "confirmation_required" } }, "precondition_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management api unavailable or Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "x-iris-v1-resource-path-exception": "role definition batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsolePeerPolicyRolesImportCsvRequest", "type": "object", "properties": { "csv": { "type": "string" }, "confirm_token": { "type": [ "string", "null" ], "writeOnly": true } }, "required": [ "csv" ], "additionalProperties": false }, "example": { "csv": "role,restricted,peers,seed_up_bps\nboat,true,boat;fiber,12500000\nfiber,true,fiber;boat,\n", "confirm_token": "candidate-bound-sha256" } } } } } }, "/api/v1/peer-policy/roles/{name}": { "put": { "operationId": "console_put_api_v1_peer_policy_roles_name", "summary": "Replace a role definition", "description": "Replace a role definition. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "dry_run", "in": "query", "required": false, "description": "1 previews the locked candidate without persistence; 0 commits after required confirmation.", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "example": 1 }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong policy ETag. Missing: 428; stale: 412; race under the policy lock: 409. Confirmation is candidate-bound at threshold zero, including every changed QoS document.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Replace a role definition response", "content": { "application/json": { "schema": { "title": "ConsolePeerPolicyRolesNameResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "candidate_revision": { "type": "integer" }, "dry_run": { "type": "boolean" }, "member_delta": { "type": "integer" }, "origin_access_lost": { "type": "integer" }, "empty_permitted_sets": { "type": "integer" }, "role_pairs_stopped": { "type": "integer" }, "qos_changed": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ] } }, "required": [ "ok", "revision", "candidate_revision", "dry_run", "member_delta", "origin_access_lost", "empty_permitted_sets", "role_pairs_stopped", "qos_changed", "requires_confirmation", "confirm_token" ], "additionalProperties": true }, "examples": { "confirmationRequired": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 1, "qos_changed": false, "requires_confirmation": true, "confirm_token": "candidate-bound-sha256" } }, "noConfirmation": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": false, "confirm_token": null } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "400": { "description": "Invalid content length", "x-iris-problem-codes": [ "invalid-content-length" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "409": { "description": "Operation backlog full or Revision conflict or Role isolated or Role reserved name", "x-iris-problem-codes": [ "operation_backlog_full", "revision_conflict", "role_isolated", "role_reserved_name" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "operation_backlog_full": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#operation_backlog_full", "title": "Operation backlog full", "status": 409, "code": "operation_backlog_full" } }, "revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#revision_conflict", "title": "Revision conflict", "status": 409, "code": "revision_conflict" } }, "role_isolated": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_isolated", "title": "Role isolated", "status": 409, "code": "role_isolated" } }, "role_reserved_name": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_reserved_name", "title": "Role reserved name", "status": 409, "code": "role_reserved_name" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "422": { "description": "Invalid policy or Invalid policy request", "x-iris-problem-codes": [ "invalid_policy", "invalid_policy_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_policy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy", "title": "Invalid policy", "status": 422, "code": "invalid_policy" } }, "invalid_policy_request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Confirmation required or Precondition required", "x-iris-problem-codes": [ "confirmation_required", "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "confirmation_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#confirmation_required", "title": "Confirmation required", "status": 428, "code": "confirmation_required" } }, "precondition_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management api unavailable or Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsolePeerPolicyRolesNameRequest", "type": "object", "properties": { "restricted": { "type": "boolean" }, "peers": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,31}$", "not": { "enum": [ "default", "legacy", "origin", "quarantine", "seeder" ] } }, "minItems": 1, "maxItems": 64, "uniqueItems": true, "x-iris-selfPeerRequired": true, "description": "Must contain the role's {name} path value; missing self returns 409 role_isolated." }, "origin": { "type": "boolean" }, "nets": { "type": "array", "items": { "type": "string", "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])(?:/(?:(?=[0-9]{1,32}$(?![\\s\\S]))0*(?:[0-9]|[12][0-9]|3[0-2])|0\\.0\\.0\\.0|0\\.0\\.0\\.1|0\\.0\\.0\\.127|0\\.0\\.0\\.15|0\\.0\\.0\\.255|0\\.0\\.0\\.3|0\\.0\\.0\\.31|0\\.0\\.0\\.63|0\\.0\\.0\\.7|0\\.0\\.1\\.255|0\\.0\\.127\\.255|0\\.0\\.15\\.255|0\\.0\\.255\\.255|0\\.0\\.3\\.255|0\\.0\\.31\\.255|0\\.0\\.63\\.255|0\\.0\\.7\\.255|0\\.1\\.255\\.255|0\\.127\\.255\\.255|0\\.15\\.255\\.255|0\\.255\\.255\\.255|0\\.3\\.255\\.255|0\\.31\\.255\\.255|0\\.63\\.255\\.255|0\\.7\\.255\\.255|1\\.255\\.255\\.255|127\\.255\\.255\\.255|128\\.0\\.0\\.0|15\\.255\\.255\\.255|192\\.0\\.0\\.0|224\\.0\\.0\\.0|240\\.0\\.0\\.0|248\\.0\\.0\\.0|252\\.0\\.0\\.0|254\\.0\\.0\\.0|255\\.0\\.0\\.0|255\\.128\\.0\\.0|255\\.192\\.0\\.0|255\\.224\\.0\\.0|255\\.240\\.0\\.0|255\\.248\\.0\\.0|255\\.252\\.0\\.0|255\\.254\\.0\\.0|255\\.255\\.0\\.0|255\\.255\\.128\\.0|255\\.255\\.192\\.0|255\\.255\\.224\\.0|255\\.255\\.240\\.0|255\\.255\\.248\\.0|255\\.255\\.252\\.0|255\\.255\\.254\\.0|255\\.255\\.255\\.0|255\\.255\\.255\\.128|255\\.255\\.255\\.192|255\\.255\\.255\\.224|255\\.255\\.255\\.240|255\\.255\\.255\\.248|255\\.255\\.255\\.252|255\\.255\\.255\\.254|255\\.255\\.255\\.255|3\\.255\\.255\\.255|31\\.255\\.255\\.255|63\\.255\\.255\\.255|7\\.255\\.255\\.255))?$(?![\\s\\S])", "description": "IPv4 address, CIDR or dotted netmask/hostmask. A decimal prefix allows at most 32 digits, including leading zeroes; valid spelling is preserved." } }, "on_stale": { "type": "string", "enum": [ "keep", "defaults" ] }, "qos": { "type": "object", "properties": { "max_peers": { "type": "integer", "minimum": 1, "maximum": 1000 }, "per_peer_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "fanout": { "type": "integer", "minimum": 1, "maximum": 1000 }, "seed_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "seed_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "max_concurrent": { "type": "integer", "minimum": 1, "maximum": 1000 }, "catalog_tick_s": { "type": "integer", "minimum": 60, "maximum": 900, "multipleOf": 60 }, "telemetry_every_ticks": { "type": "integer", "minimum": 1, "maximum": 60 }, "telemetry_pause": { "type": "boolean" }, "request_peer_speed_limit_bps": { "type": "integer", "minimum": 0, "maximum": 1000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "announce_min_interval_s": { "type": "integer", "minimum": 10, "maximum": 300 }, "numwant": { "type": "integer", "minimum": 4, "maximum": 200 }, "handout_budget": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "additionalProperties": false, "description": "Replace this layer with any supported subset; an empty object clears it. Cross-field and restricted-role semantics are validated by the policy transaction." }, "confirm_token": { "type": [ "string", "null" ], "writeOnly": true }, "qos_state": { "$ref": "#/components/schemas/TrackerQosStateMap" } }, "required": [], "additionalProperties": false }, "example": { "restricted": true, "peers": [ "boat" ], "origin": true, "nets": [], "on_stale": "keep", "qos": {}, "confirm_token": "candidate-bound-sha256" } } } } }, "delete": { "operationId": "console_delete_api_v1_peer_policy_roles_name", "summary": "Delete a role definition", "description": "Delete a role definition. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "dry_run", "in": "query", "required": false, "description": "1 previews the locked candidate without persistence; 0 commits after required confirmation.", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "example": 1 }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong policy ETag. Missing: 428; stale: 412; race under the policy lock: 409. Confirmation is candidate-bound at threshold zero, including every changed QoS document.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Dry-run candidate and confirmation preview", "content": { "application/json": { "schema": { "title": "ConsolePeerPolicyRolesNameResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "candidate_revision": { "type": "integer" }, "dry_run": { "type": "boolean" }, "member_delta": { "type": "integer" }, "origin_access_lost": { "type": "integer" }, "empty_permitted_sets": { "type": "integer" }, "role_pairs_stopped": { "type": "integer" }, "qos_changed": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ] } }, "required": [ "ok", "revision", "candidate_revision", "dry_run", "member_delta", "origin_access_lost", "empty_permitted_sets", "role_pairs_stopped", "qos_changed", "requires_confirmation", "confirm_token" ], "additionalProperties": true }, "examples": { "confirmationRequired": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 1, "qos_changed": false, "requires_confirmation": true, "confirm_token": "candidate-bound-sha256" } }, "noConfirmation": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": false, "confirm_token": null } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "204": { "description": "Role deleted; no body", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid content length", "x-iris-problem-codes": [ "invalid-content-length" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Role not found or Route not found", "x-iris-problem-codes": [ "role_not_found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "role_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found", "title": "Role not found", "status": 404, "code": "role_not_found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "409": { "description": "Operation backlog full or Revision conflict or Role in use or Role reserved name", "x-iris-problem-codes": [ "operation_backlog_full", "revision_conflict", "role_in_use", "role_reserved_name" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "operation_backlog_full": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#operation_backlog_full", "title": "Operation backlog full", "status": 409, "code": "operation_backlog_full" } }, "revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#revision_conflict", "title": "Revision conflict", "status": 409, "code": "revision_conflict" } }, "role_in_use": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_in_use", "title": "Role in use", "status": 409, "code": "role_in_use" } }, "role_reserved_name": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_reserved_name", "title": "Role reserved name", "status": 409, "code": "role_reserved_name" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "422": { "description": "Invalid policy or Invalid policy request", "x-iris-problem-codes": [ "invalid_policy", "invalid_policy_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_policy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy", "title": "Invalid policy", "status": 422, "code": "invalid_policy" } }, "invalid_policy_request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Confirmation required or Precondition required", "x-iris-problem-codes": [ "confirmation_required", "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "confirmation_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#confirmation_required", "title": "Confirmation required", "status": 428, "code": "confirmation_required" } }, "precondition_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management api unavailable or Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm_token": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "example": { "confirm_token": "candidate-bound-sha256" } } } } } }, "/api/v1/peer-policy/qos": { "put": { "operationId": "console_put_api_v1_peer_policy_qos", "summary": "Replace global or role QoS", "description": "Replace global or role QoS. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "dry_run", "in": "query", "required": false, "description": "1 previews the locked candidate without persistence; 0 commits after required confirmation.", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "example": 1 }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong policy ETag. Missing: 428; stale: 412; race under the policy lock: 409. Confirmation is candidate-bound at threshold zero, including every changed QoS document.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Replace global or role QoS response", "content": { "application/json": { "schema": { "title": "ConsolePeerPolicyQosResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "candidate_revision": { "type": "integer" }, "dry_run": { "type": "boolean" }, "member_delta": { "type": "integer" }, "origin_access_lost": { "type": "integer" }, "empty_permitted_sets": { "type": "integer" }, "role_pairs_stopped": { "type": "integer" }, "qos_changed": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ] } }, "required": [ "ok", "revision", "candidate_revision", "dry_run", "member_delta", "origin_access_lost", "empty_permitted_sets", "role_pairs_stopped", "qos_changed", "requires_confirmation", "confirm_token" ], "additionalProperties": true }, "examples": { "confirmationRequired": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": true, "requires_confirmation": true, "confirm_token": "candidate-bound-sha256" } }, "noConfirmation": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": false, "confirm_token": null } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "400": { "description": "Invalid content length", "x-iris-problem-codes": [ "invalid-content-length" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Role not found or Route not found", "x-iris-problem-codes": [ "role_not_found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "role_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found", "title": "Role not found", "status": 404, "code": "role_not_found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "409": { "description": "Operation backlog full or Revision conflict or Role reserved name", "x-iris-problem-codes": [ "operation_backlog_full", "revision_conflict", "role_reserved_name" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "operation_backlog_full": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#operation_backlog_full", "title": "Operation backlog full", "status": 409, "code": "operation_backlog_full" } }, "revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#revision_conflict", "title": "Revision conflict", "status": 409, "code": "revision_conflict" } }, "role_reserved_name": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_reserved_name", "title": "Role reserved name", "status": 409, "code": "role_reserved_name" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "422": { "description": "Invalid policy or Invalid policy request", "x-iris-problem-codes": [ "invalid_policy", "invalid_policy_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_policy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy", "title": "Invalid policy", "status": 422, "code": "invalid_policy" } }, "invalid_policy_request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Confirmation required or Precondition required", "x-iris-problem-codes": [ "confirmation_required", "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "confirmation_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#confirmation_required", "title": "Confirmation required", "status": 428, "code": "confirmation_required" } }, "precondition_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management api unavailable or Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsolePeerPolicyQosRequest", "type": "object", "properties": { "qos": { "type": "object", "properties": { "max_peers": { "type": "integer", "minimum": 1, "maximum": 1000 }, "per_peer_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "fanout": { "type": "integer", "minimum": 1, "maximum": 1000 }, "seed_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "seed_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "max_concurrent": { "type": "integer", "minimum": 1, "maximum": 1000 }, "catalog_tick_s": { "type": "integer", "minimum": 60, "maximum": 900, "multipleOf": 60 }, "telemetry_every_ticks": { "type": "integer", "minimum": 1, "maximum": 60 }, "telemetry_pause": { "type": "boolean" }, "request_peer_speed_limit_bps": { "type": "integer", "minimum": 0, "maximum": 1000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "announce_min_interval_s": { "type": "integer", "minimum": 10, "maximum": 300 }, "numwant": { "type": "integer", "minimum": 4, "maximum": 200 }, "handout_budget": { "type": "integer", "minimum": 0, "maximum": 1000 }, "on_stale": { "type": "string", "enum": [ "keep", "defaults" ] }, "origin_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "origin_per_torrent_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "origin_max_peers": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "additionalProperties": false, "description": "Replace this layer with any supported subset; an empty object clears it. Cross-field and restricted-role semantics are validated by the policy transaction." }, "qos_state": { "$ref": "#/components/schemas/TrackerQosStateMap" }, "role": { "type": [ "string", "null" ] }, "confirm_token": { "type": [ "string", "null" ], "writeOnly": true } }, "required": [], "additionalProperties": false, "anyOf": [ { "required": [ "qos" ] }, { "required": [ "qos_state" ] } ], "description": "Global qos_state is stored at roles.qos_state_default. Role qos_state is stored at roles.defs..qos_state. Omission preserves either stored layer; an explicit empty object clears the supplied layer.", "allOf": [ { "if": { "required": [ "role" ], "properties": { "role": { "type": "string" } } }, "then": { "properties": { "qos": { "type": "object", "properties": { "max_peers": { "type": "integer", "minimum": 1, "maximum": 1000 }, "per_peer_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "fanout": { "type": "integer", "minimum": 1, "maximum": 1000 }, "seed_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "seed_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "max_concurrent": { "type": "integer", "minimum": 1, "maximum": 1000 }, "catalog_tick_s": { "type": "integer", "minimum": 60, "maximum": 900, "multipleOf": 60 }, "telemetry_every_ticks": { "type": "integer", "minimum": 1, "maximum": 60 }, "telemetry_pause": { "type": "boolean" }, "request_peer_speed_limit_bps": { "type": "integer", "minimum": 0, "maximum": 1000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "announce_min_interval_s": { "type": "integer", "minimum": 10, "maximum": 300 }, "numwant": { "type": "integer", "minimum": 4, "maximum": 200 }, "handout_budget": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "additionalProperties": false, "description": "Replace this layer with any supported subset; an empty object clears it. Cross-field and restricted-role semantics are validated by the policy transaction." } } } } ] }, "example": { "qos": { "numwant": 25 }, "qos_state": { "seeder": { "announce_min_interval_s": 120, "numwant": 4 } }, "role": "boat", "confirm_token": "candidate-bound-sha256" } } } } } }, "/api/v1/peer-policy/origin-enforcement": { "get": { "operationId": "console_get_api_v1_peer_policy_origin_enforcement", "summary": "Read reviewed distribution restrictions", "description": "Read reviewed distribution restrictions. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Reviewed approval or count-only application evidence", "headers": { "ETag": { "schema": { "type": "string", "pattern": "^\"origin-enforcement-[0-9]+\"$" }, "example": "\"origin-enforcement-0\"" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0 }, "policy_revision": { "type": "integer", "minimum": 0 }, "approved_ip_count": { "type": "integer", "minimum": 0 }, "approved_device_count": { "type": "integer", "minimum": 0 }, "new_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "new_device_count": { "type": [ "integer", "null" ], "minimum": 0 }, "retained_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "proposed_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "proposed_device_count": { "type": [ "integer", "null" ], "minimum": 0 }, "shared_conflict_count": { "type": [ "integer", "null" ], "minimum": 0 }, "protected_conflict_count": { "type": [ "integer", "null" ], "minimum": 0 }, "applied_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "applied_device_count": { "type": [ "integer", "null" ], "minimum": 0 }, "mode": { "enum": [ "preflight", "enforce" ] }, "state": { "enum": [ "degraded", "enforced", "pending", "preflight", "review_required", "unavailable" ] }, "max_new_ips": { "type": "integer", "minimum": 0, "maximum": 1000 }, "max_new_devices": { "type": "integer", "minimum": 0, "maximum": 1000 }, "reason": { "enum": [ null, "application_pending", "application_state_unavailable", "apply_failed", "aria_unavailable", "control_state_unavailable", "device_budget_exceeded", "endpoint_set_changed", "endpoint_state_unavailable", "ip_budget_exceeded", "origin_mismatch", "origin_unknown", "origin_unobserved", "policy_changed", "policy_unavailable", "protected_address", "retention_capacity_exceeded", "session_changed", "shared_address" ] }, "last_verified_at": { "type": [ "number", "null" ], "minimum": 0 }, "blockers": { "type": "array", "maxItems": 18, "items": { "enum": [ "application_pending", "application_state_unavailable", "apply_failed", "aria_unavailable", "control_state_unavailable", "device_budget_exceeded", "endpoint_set_changed", "endpoint_state_unavailable", "ip_budget_exceeded", "origin_mismatch", "origin_unknown", "origin_unobserved", "policy_changed", "policy_unavailable", "protected_address", "retention_capacity_exceeded", "session_changed", "shared_address" ] } } }, "required": [ "revision", "policy_revision", "approved_ip_count", "approved_device_count", "new_ip_count", "new_device_count", "retained_ip_count", "proposed_ip_count", "proposed_device_count", "shared_conflict_count", "protected_conflict_count", "applied_ip_count", "applied_device_count", "mode", "state", "max_new_ips", "max_new_devices", "reason", "last_verified_at", "blockers" ], "additionalProperties": false, "description": "Count-only distribution-access approval and application evidence. Mode is requested intent; state is separately verified tracker evidence. A saved approval is pending, never immediate proof of enforcement. Null counts mean unavailable. No addresses or private application journal are exposed.", "allOf": [ { "if": { "properties": { "state": { "const": "enforced" } } }, "then": { "properties": { "mode": { "const": "enforce" }, "reason": { "const": null }, "blockers": { "maxItems": 0 }, "applied_ip_count": { "type": "integer", "minimum": 0 }, "applied_device_count": { "type": "integer", "minimum": 0 }, "last_verified_at": { "type": "number", "exclusiveMinimum": 0 } } } } ] }, "example": { "revision": 0, "policy_revision": 4, "mode": "preflight", "max_new_ips": 10, "max_new_devices": 10, "approved_ip_count": 0, "approved_device_count": 0, "new_ip_count": 2, "new_device_count": 3, "retained_ip_count": 0, "proposed_ip_count": 2, "proposed_device_count": 3, "shared_conflict_count": 0, "protected_conflict_count": 0, "state": "preflight", "reason": null, "applied_ip_count": null, "applied_device_count": null, "last_verified_at": null, "blockers": [] } } } }, "400": { "description": "Invalid content length or Request body not supported", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management api unavailable or Origin enforcement unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "origin_enforcement_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "origin_enforcement_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#origin_enforcement_unavailable", "title": "Origin enforcement unavailable", "status": 503, "code": "origin_enforcement_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } } }, "put": { "operationId": "console_put_api_v1_peer_policy_origin_enforcement", "summary": "Review or apply distribution restrictions", "description": "Review or apply distribution restrictions. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong control ETag from GET distribution access; distinct from the policy revision in the body. Required for both preview and commit. Missing: 428; malformed, weak or stale: 412.", "schema": { "type": "string", "pattern": "^\"origin-enforcement-[0-9]+\"$" }, "example": "\"origin-enforcement-0\"" } ], "responses": { "200": { "description": "Reviewed approval or count-only application evidence", "headers": { "ETag": { "schema": { "type": "string", "pattern": "^\"origin-enforcement-[0-9]+\"$" }, "example": "\"origin-enforcement-0\"" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0 }, "policy_revision": { "type": "integer", "minimum": 0 }, "approved_ip_count": { "type": "integer", "minimum": 0 }, "approved_device_count": { "type": "integer", "minimum": 0 }, "new_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "new_device_count": { "type": [ "integer", "null" ], "minimum": 0 }, "retained_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "proposed_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "proposed_device_count": { "type": [ "integer", "null" ], "minimum": 0 }, "shared_conflict_count": { "type": [ "integer", "null" ], "minimum": 0 }, "protected_conflict_count": { "type": [ "integer", "null" ], "minimum": 0 }, "applied_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "applied_device_count": { "type": [ "integer", "null" ], "minimum": 0 }, "mode": { "enum": [ "preflight", "enforce" ] }, "state": { "enum": [ "degraded", "enforced", "pending", "preflight", "review_required", "unavailable" ] }, "max_new_ips": { "type": "integer", "minimum": 0, "maximum": 1000 }, "max_new_devices": { "type": "integer", "minimum": 0, "maximum": 1000 }, "reason": { "enum": [ null, "application_pending", "application_state_unavailable", "apply_failed", "aria_unavailable", "control_state_unavailable", "device_budget_exceeded", "endpoint_set_changed", "endpoint_state_unavailable", "ip_budget_exceeded", "origin_mismatch", "origin_unknown", "origin_unobserved", "policy_changed", "policy_unavailable", "protected_address", "retention_capacity_exceeded", "session_changed", "shared_address" ] }, "last_verified_at": { "type": [ "number", "null" ], "minimum": 0 }, "blockers": { "type": "array", "maxItems": 18, "items": { "enum": [ "application_pending", "application_state_unavailable", "apply_failed", "aria_unavailable", "control_state_unavailable", "device_budget_exceeded", "endpoint_set_changed", "endpoint_state_unavailable", "ip_budget_exceeded", "origin_mismatch", "origin_unknown", "origin_unobserved", "policy_changed", "policy_unavailable", "protected_address", "retention_capacity_exceeded", "session_changed", "shared_address" ] } }, "dry_run": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" } }, "required": [ "revision", "policy_revision", "approved_ip_count", "approved_device_count", "new_ip_count", "new_device_count", "retained_ip_count", "proposed_ip_count", "proposed_device_count", "shared_conflict_count", "protected_conflict_count", "applied_ip_count", "applied_device_count", "mode", "state", "max_new_ips", "max_new_devices", "reason", "last_verified_at", "blockers", "dry_run", "requires_confirmation", "confirm_token" ], "additionalProperties": false, "description": "Count-only distribution-access approval and application evidence. Mode is requested intent; state is separately verified tracker evidence. A saved approval is pending, never immediate proof of enforcement. Null counts mean unavailable. No addresses or private application journal are exposed.", "allOf": [ { "if": { "properties": { "dry_run": { "const": false } } }, "then": { "properties": { "requires_confirmation": { "const": false }, "confirm_token": { "const": null }, "state": { "const": "pending" }, "applied_ip_count": { "const": null }, "applied_device_count": { "const": null }, "last_verified_at": { "const": null } } }, "else": { "properties": { "requires_confirmation": { "const": true } } } } ] }, "examples": { "preview": { "value": { "revision": 0, "policy_revision": 4, "mode": "enforce", "max_new_ips": 10, "max_new_devices": 10, "approved_ip_count": 0, "approved_device_count": 0, "new_ip_count": 2, "new_device_count": 3, "retained_ip_count": 0, "proposed_ip_count": 2, "proposed_device_count": 3, "shared_conflict_count": 0, "protected_conflict_count": 0, "state": "preflight", "reason": null, "applied_ip_count": null, "applied_device_count": null, "last_verified_at": null, "blockers": [], "dry_run": true, "requires_confirmation": true, "confirm_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "blocked": { "value": { "revision": 0, "policy_revision": 4, "mode": "enforce", "max_new_ips": 10, "max_new_devices": 10, "approved_ip_count": 0, "approved_device_count": 0, "new_ip_count": 2, "new_device_count": 3, "retained_ip_count": 0, "proposed_ip_count": 2, "proposed_device_count": 3, "shared_conflict_count": 1, "protected_conflict_count": 0, "state": "preflight", "reason": null, "applied_ip_count": null, "applied_device_count": null, "last_verified_at": null, "blockers": [ "shared_address" ], "dry_run": true, "requires_confirmation": true, "confirm_token": null } }, "accepted": { "value": { "revision": 1, "policy_revision": 4, "mode": "enforce", "max_new_ips": 10, "max_new_devices": 10, "approved_ip_count": 2, "approved_device_count": 3, "new_ip_count": 2, "new_device_count": 3, "retained_ip_count": 0, "proposed_ip_count": 2, "proposed_device_count": 3, "shared_conflict_count": 0, "protected_conflict_count": 0, "state": "pending", "reason": null, "applied_ip_count": null, "applied_device_count": null, "last_verified_at": null, "blockers": [], "dry_run": false, "requires_confirmation": false, "confirm_token": null } } } } } }, "400": { "description": "Invalid content length", "x-iris-problem-codes": [ "invalid-content-length" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "409": { "description": "Origin enforcement blocked or Origin review stale or Policy revision conflict", "x-iris-problem-codes": [ "origin_enforcement_blocked", "origin_review_stale", "policy_revision_conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "origin_enforcement_blocked": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#origin_enforcement_blocked", "title": "Origin enforcement blocked", "status": 409, "code": "origin_enforcement_blocked" } }, "origin_review_stale": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#origin_review_stale", "title": "Origin review stale", "status": 409, "code": "origin_review_stale" } }, "policy_revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_revision_conflict", "title": "Policy revision conflict", "status": 409, "code": "policy_revision_conflict" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "422": { "description": "Invalid origin enforcement", "x-iris-problem-codes": [ "invalid_origin_enforcement" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_origin_enforcement", "title": "Invalid origin enforcement", "status": 422, "code": "invalid_origin_enforcement" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Precondition required", "x-iris-problem-codes": [ "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management api unavailable or Origin enforcement unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "origin_enforcement_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "origin_enforcement_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#origin_enforcement_unavailable", "title": "Origin enforcement unavailable", "status": 503, "code": "origin_enforcement_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "enum": [ "preflight", "enforce" ] }, "max_new_ips": { "type": "integer", "minimum": 0, "maximum": 1000 }, "max_new_devices": { "type": "integer", "minimum": 0, "maximum": 1000 }, "if_policy_revision": { "type": "integer", "minimum": 0 }, "dry_run": { "type": "boolean" }, "confirm_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "mode", "max_new_ips", "max_new_devices", "if_policy_revision", "dry_run" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "dry_run": { "const": false } } }, "then": { "required": [ "confirm_token" ] } } ], "description": "Preview with dry_run=true using the current control ETag and policy revision. Commit the exact same mode, limits and revisions with dry_run=false and the returned confirmation token. Both enabling and disabling require a preview bound to the exact reviewed policy, origin and peer bindings. A changed peer set requires a new preview even if counts are unchanged." }, "example": { "mode": "enforce", "max_new_ips": 10, "max_new_devices": 10, "if_policy_revision": 4, "dry_run": true } } } } } }, "/api/v1/devices/{device_id}/role": { "post": { "operationId": "console_post_api_v1_devices_device_id_role", "summary": "Set a device role", "description": "Set a device role. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "dry_run", "in": "query", "required": false, "description": "1 previews the locked candidate without persistence; 0 commits after required confirmation.", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "example": 1 }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong policy ETag. Missing: 428; stale: 412; race under the policy lock: 409. Confirmation is candidate-bound at threshold zero, including every changed QoS document.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Set a device role response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdRoleResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "candidate_revision": { "type": "integer" }, "dry_run": { "type": "boolean" }, "member_delta": { "type": "integer" }, "origin_access_lost": { "type": "integer" }, "empty_permitted_sets": { "type": "integer" }, "role_pairs_stopped": { "type": "integer" }, "qos_changed": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ] }, "partial": { "type": "boolean" }, "applied": { "type": "integer" }, "failed": { "title": "ConsoleDevicesDeviceIdRoleResponseFailed", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "direction": { "type": "string" }, "role_drift": { "title": "ConsoleDevicesDeviceIdRoleResponseRole_Drift", "type": "object", "properties": { "count": { "type": "integer" }, "device_ids": { "type": "array", "items": { "type": "string" } }, "truncated": { "type": "boolean" } }, "required": [ "count", "device_ids", "truncated" ], "additionalProperties": true } }, "required": [ "ok", "revision", "dry_run", "partial", "applied", "failed", "direction", "role_drift" ], "additionalProperties": true }, "examples": { "confirmationRequired": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 1, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": true, "confirm_token": "candidate-bound-sha256", "partial": false, "applied": 1, "failed": {}, "direction": "tighten", "role_drift": { "count": 0, "device_ids": [], "truncated": false } } }, "noConfirmation": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": false, "confirm_token": null, "partial": false, "applied": 1, "failed": {}, "direction": "tighten", "role_drift": { "count": 0, "device_ids": [], "truncated": false } } }, "unchangedMembership": { "value": { "ok": true, "revision": 5, "dry_run": false, "partial": false, "applied": 1, "failed": {}, "direction": "neutral", "role_drift": { "count": 0, "device_ids": [], "truncated": false } } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "400": { "description": "Invalid content length or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Device not found or Role not found or Route not found", "x-iris-problem-codes": [ "device_not_found", "role_not_found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "device_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#device_not_found", "title": "Device not found", "status": 404, "code": "device_not_found" } }, "role_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found", "title": "Role not found", "status": 404, "code": "role_not_found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "409": { "description": "Operation backlog full or Revision conflict or Role reserved name or Role shadowed by assignment", "x-iris-problem-codes": [ "operation_backlog_full", "revision_conflict", "role_reserved_name", "role_shadowed_by_assignment" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "operation_backlog_full": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#operation_backlog_full", "title": "Operation backlog full", "status": 409, "code": "operation_backlog_full" } }, "revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#revision_conflict", "title": "Revision conflict", "status": 409, "code": "revision_conflict" } }, "role_reserved_name": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_reserved_name", "title": "Role reserved name", "status": 409, "code": "role_reserved_name" } }, "role_shadowed_by_assignment": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_shadowed_by_assignment", "title": "Role shadowed by assignment", "status": 409, "code": "role_shadowed_by_assignment" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Bad role or Incomparable role change or Invalid policy or Invalid policy request", "x-iris-problem-codes": [ "bad_role", "incomparable_role_change", "invalid_policy", "invalid_policy_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_role": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#bad_role", "title": "Bad role", "status": 422, "code": "bad_role" } }, "incomparable_role_change": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#incomparable_role_change", "title": "Incomparable role change", "status": 422, "code": "incomparable_role_change" } }, "invalid_policy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy", "title": "Invalid policy", "status": 422, "code": "invalid_policy" } }, "invalid_policy_request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Confirmation required or Precondition required", "x-iris-problem-codes": [ "confirmation_required", "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "confirmation_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#confirmation_required", "title": "Confirmation required", "status": 428, "code": "confirmation_required" } }, "precondition_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Fleet write failed or Management api unavailable or Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "fleet_write_failed", "management-api-unavailable", "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "fleet_write_failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#fleet_write_failed", "title": "Fleet write failed", "status": 503, "code": "fleet_write_failed" } }, "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdRoleRequest", "type": "object", "properties": { "role": { "type": [ "string", "null" ] }, "confirm_token": { "type": [ "string", "null" ], "writeOnly": true } }, "required": [ "role" ], "additionalProperties": false }, "example": { "role": "boat", "confirm_token": "candidate-bound-sha256" } } } } } }, "/api/v1/devices/bulk-role": { "post": { "operationId": "console_post_api_v1_devices_bulk_role", "summary": "Set device roles in bulk", "description": "Set device roles in bulk. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. fleet batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "dry_run", "in": "query", "required": false, "description": "1 previews the locked candidate without persistence; 0 commits after required confirmation.", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "example": 1 }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong policy ETag. Missing: 428; stale: 412; race under the policy lock: 409. Confirmation is candidate-bound at threshold zero, including every changed QoS document.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Set device roles in bulk response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesBulkRoleResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "candidate_revision": { "type": "integer" }, "dry_run": { "type": "boolean" }, "member_delta": { "type": "integer" }, "origin_access_lost": { "type": "integer" }, "empty_permitted_sets": { "type": "integer" }, "role_pairs_stopped": { "type": "integer" }, "qos_changed": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ] }, "partial": { "type": "boolean" }, "applied": { "type": "integer" }, "failed": { "title": "ConsoleDevicesBulkRoleResponseFailed", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "direction": { "type": "string" }, "role_drift": { "title": "ConsoleDevicesBulkRoleResponseRole_Drift", "type": "object", "properties": { "count": { "type": "integer" }, "device_ids": { "type": "array", "items": { "type": "string" } }, "truncated": { "type": "boolean" } }, "required": [ "count", "device_ids", "truncated" ], "additionalProperties": true } }, "required": [ "ok", "revision", "dry_run", "partial", "applied", "failed", "direction", "role_drift" ], "additionalProperties": true }, "examples": { "confirmationRequired": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 1, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": true, "confirm_token": "candidate-bound-sha256", "partial": false, "applied": 2, "failed": {}, "direction": "tighten", "role_drift": { "count": 0, "device_ids": [], "truncated": false } } }, "noConfirmation": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": false, "confirm_token": null, "partial": false, "applied": 2, "failed": {}, "direction": "tighten", "role_drift": { "count": 0, "device_ids": [], "truncated": false } } }, "unchangedMembership": { "value": { "ok": true, "revision": 5, "dry_run": false, "partial": false, "applied": 2, "failed": {}, "direction": "neutral", "role_drift": { "count": 0, "device_ids": [], "truncated": false } } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "400": { "description": "Invalid content length or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Role not found or Route not found", "x-iris-problem-codes": [ "role_not_found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "role_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found", "title": "Role not found", "status": 404, "code": "role_not_found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "409": { "description": "Operation backlog full or Revision conflict or Role reserved name or Role shadowed by assignment", "x-iris-problem-codes": [ "operation_backlog_full", "revision_conflict", "role_reserved_name", "role_shadowed_by_assignment" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "operation_backlog_full": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#operation_backlog_full", "title": "Operation backlog full", "status": 409, "code": "operation_backlog_full" } }, "revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#revision_conflict", "title": "Revision conflict", "status": 409, "code": "revision_conflict" } }, "role_reserved_name": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_reserved_name", "title": "Role reserved name", "status": 409, "code": "role_reserved_name" } }, "role_shadowed_by_assignment": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_shadowed_by_assignment", "title": "Role shadowed by assignment", "status": 409, "code": "role_shadowed_by_assignment" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Bad role or Incomparable role change or Invalid policy or Invalid policy request or Mixed role direction", "x-iris-problem-codes": [ "bad_role", "incomparable_role_change", "invalid_policy", "invalid_policy_request", "mixed_role_direction" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_role": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#bad_role", "title": "Bad role", "status": 422, "code": "bad_role" } }, "incomparable_role_change": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#incomparable_role_change", "title": "Incomparable role change", "status": 422, "code": "incomparable_role_change" } }, "invalid_policy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy", "title": "Invalid policy", "status": 422, "code": "invalid_policy" } }, "invalid_policy_request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } }, "mixed_role_direction": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#mixed_role_direction", "title": "Mixed role direction", "status": 422, "code": "mixed_role_direction" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Confirmation required or Precondition required", "x-iris-problem-codes": [ "confirmation_required", "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "confirmation_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#confirmation_required", "title": "Confirmation required", "status": 428, "code": "confirmation_required" } }, "precondition_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Fleet write failed or Management api unavailable or Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "fleet_write_failed", "management-api-unavailable", "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "fleet_write_failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#fleet_write_failed", "title": "Fleet write failed", "status": 503, "code": "fleet_write_failed" } }, "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "x-iris-v1-resource-path-exception": "fleet batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleDevicesBulkRoleRequest", "type": "object", "properties": { "device_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 10000 }, "role": { "type": [ "string", "null" ] }, "confirm_token": { "type": [ "string", "null" ], "writeOnly": true } }, "required": [ "device_ids", "role" ], "additionalProperties": false }, "example": { "device_ids": [ "edge-01", "edge-02" ], "role": "boat", "confirm_token": "candidate-bound-sha256" } } } } } }, "/api/v1/devices/{device_id}/effective-qos": { "get": { "operationId": "console_get_api_v1_devices_device_id_effective_qos", "summary": "Explain effective device QoS", "description": "Explain effective device QoS. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "tracker_state", "in": "query", "required": false, "description": "Selects the seeder or leecher tracker cadence explanation. Omission preserves the v1 scalar-only response bytes.", "schema": { "type": "string", "enum": [ "seeder", "leecher" ] }, "example": "seeder" } ], "responses": { "200": { "description": "Explain effective device QoS response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponse", "type": "object", "properties": { "revision": { "type": "integer" }, "degraded": { "type": "boolean" }, "fail_closed": { "type": "boolean" }, "device_id": { "type": "string" }, "delivery_state": { "type": "string", "const": "pre-instructions", "deprecated": true, "description": "Legacy Phase 0 compatibility sentinel. Always pre-instructions; use instruction for current delivery and application status." }, "qos": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQos", "type": "object", "properties": { "max_peers": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosMax_Peers", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "per_peer_bps": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosPer_Peer_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "fanout": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosFanout", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "seed_up_bps": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosSeed_Up_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" }, "derived_from": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosSeed_Up_BpsDerived_From", "type": "object", "properties": { "per_peer_bps": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosSeed_Up_BpsDerived_FromPer_Peer_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "fanout": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosSeed_Up_BpsDerived_FromFanout", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true } }, "required": [ "per_peer_bps", "fanout" ], "additionalProperties": true } }, "required": [ "value", "source" ], "additionalProperties": true }, "seed_down_bps": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosSeed_Down_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" }, "derived_from": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosSeed_Down_BpsDerived_From", "type": "object", "properties": { "per_peer_bps": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosSeed_Down_BpsDerived_FromPer_Peer_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "fanout": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosSeed_Down_BpsDerived_FromFanout", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true } }, "required": [ "per_peer_bps", "fanout" ], "additionalProperties": true } }, "required": [ "value", "source" ], "additionalProperties": true }, "leech_up_bps": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosLeech_Up_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" }, "derived_from": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosLeech_Up_BpsDerived_From", "type": "object", "properties": { "per_peer_bps": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosLeech_Up_BpsDerived_FromPer_Peer_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "fanout": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosLeech_Up_BpsDerived_FromFanout", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true } }, "required": [ "per_peer_bps", "fanout" ], "additionalProperties": true } }, "required": [ "value", "source" ], "additionalProperties": true }, "leech_down_bps": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosLeech_Down_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" }, "derived_from": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosLeech_Down_BpsDerived_From", "type": "object", "properties": { "per_peer_bps": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosLeech_Down_BpsDerived_FromPer_Peer_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "fanout": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosLeech_Down_BpsDerived_FromFanout", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true } }, "required": [ "per_peer_bps", "fanout" ], "additionalProperties": true } }, "required": [ "value", "source" ], "additionalProperties": true }, "overall_up_bps": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosOverall_Up_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "overall_down_bps": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosOverall_Down_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "max_concurrent": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosMax_Concurrent", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "request_peer_speed_limit_bps": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosRequest_Peer_Speed_Limit_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "announce_min_interval_s": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosAnnounce_Min_Interval_S", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "numwant": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosNumwant", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" }, "effective_ceiling": { "type": "integer" }, "runtime_request_zero": { "type": "string" }, "constraint_source": { "type": "string" } }, "required": [ "value", "source", "effective_ceiling", "runtime_request_zero", "constraint_source" ], "additionalProperties": true }, "handout_budget": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosHandout_Budget", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "catalog_tick_s": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosCatalog_Tick_S", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" }, "offline_horizon_s": { "type": "integer" }, "heartbeat_always": { "type": "boolean" } }, "required": [ "value", "source", "offline_horizon_s", "heartbeat_always" ], "additionalProperties": true }, "telemetry_every_ticks": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosTelemetry_Every_Ticks", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "peer_telemetry_interval_s": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosPeer_Telemetry_Interval_S", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "telemetry_pause": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosTelemetry_Pause", "type": "object", "properties": { "value": { "type": "boolean" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "on_stale": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosOn_Stale", "type": "object", "properties": { "value": { "type": "string" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "origin_up_bps": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosOrigin_Up_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "origin_per_torrent_up_bps": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosOrigin_Per_Torrent_Up_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "origin_max_peers": { "title": "ConsoleDevicesDeviceIdEffectiveQosResponseQosOrigin_Max_Peers", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true } }, "required": [ "max_peers", "per_peer_bps", "fanout", "seed_up_bps", "seed_down_bps", "leech_up_bps", "leech_down_bps", "overall_up_bps", "overall_down_bps", "max_concurrent", "request_peer_speed_limit_bps", "announce_min_interval_s", "numwant", "handout_budget", "catalog_tick_s", "telemetry_every_ticks", "peer_telemetry_interval_s", "telemetry_pause", "on_stale", "origin_up_bps", "origin_per_torrent_up_bps", "origin_max_peers" ], "additionalProperties": true }, "instruction": { "type": "object", "properties": { "display_state": { "type": "string", "enum": [ "applied", "lkg", "stale", "rejected", "tracker-only", "pre-instructions", "unknown", "unavailable", "pending", "forbidden", "floor_reset", "none", "revoked" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 96 }, "evidence": { "type": "string", "enum": [ "agent-asserted", "server-observed" ] }, "underlying_state": { "type": [ "string", "null" ], "enum": [ "allowlist_expired", "applied", "audience_mismatch", "floor_reset", "instr_forbidden", "instr_pending", "instr_unavailable", "key_rejected", "lkg", "lkg_rejected", "lkg_unreadable", "none", "oversize", "reasserted", "rollback_rejected", "stale_expired", "tamper_rejected", "tracker-only", "verifier_missing", null ] }, "underlying_label": { "type": "string", "minLength": 1, "maxLength": 96 }, "underlying_evidence": { "type": "string", "const": "agent-asserted" }, "reason": { "type": [ "string", "null" ], "enum": [ "bad_mac", "unknown_key", null ] }, "reported_instr_serial": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "accepted_identity": { "oneOf": [ { "type": "object", "required": [ "epoch", "instr_serial", "policy_revision" ], "additionalProperties": false, "properties": { "epoch": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "instr_serial": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "policy_revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } } }, { "type": "null" } ], "description": "Complete accepted-envelope identity asserted by the agent. Null means no complete accepted identity was reported." }, "verify_level": { "type": [ "string", "null" ], "enum": [ "sig", "none", null ] }, "pointer_skew": { "type": [ "boolean", "null" ] }, "qos_drift_count": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 49 }, "report_age_seconds": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "report_stale": { "type": [ "boolean", "null" ] }, "revoked": { "type": [ "boolean", "null" ] }, "revocation_evidence": { "type": "string", "const": "server-observed" } }, "required": [ "display_state", "label", "evidence", "underlying_state", "underlying_label", "underlying_evidence", "reason", "reported_instr_serial", "accepted_identity", "verify_level", "pointer_skew", "qos_drift_count", "report_age_seconds", "report_stale", "revoked", "revocation_evidence" ], "additionalProperties": false, "description": "Canonical bounded instruction display projection. Device facts remain assertions; server-observed revocation and report age may take display precedence while retaining the underlying report." }, "tracker_state": { "type": "string", "enum": [ "seeder", "leecher" ] }, "tracker_qos": { "type": "object", "additionalProperties": false, "properties": { "announce_min_interval_s": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": "integer", "minimum": 10, "maximum": 300 }, "source": { "type": "string", "pattern": "^(?:builtin|global|global-state:(?:seeder|leecher)|role:[a-z0-9][a-z0-9._-]{0,31}|role-state:[a-z0-9][a-z0-9._-]{0,31}:(?:seeder|leecher))$" } }, "required": [ "value", "source" ] }, "numwant": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": "integer", "minimum": 4, "maximum": 200 }, "source": { "type": "string", "pattern": "^(?:builtin|global|global-state:(?:seeder|leecher)|role:[a-z0-9][a-z0-9._-]{0,31}|role-state:[a-z0-9][a-z0-9._-]{0,31}:(?:seeder|leecher))$" }, "effective_ceiling": { "type": "integer", "minimum": 4, "maximum": 50 }, "runtime_request_zero": { "type": "string", "const": "disabled" }, "constraint_source": { "type": "string", "const": "pinned-aria2-client" } }, "required": [ "value", "source", "effective_ceiling", "runtime_request_zero", "constraint_source" ] } }, "required": [ "announce_min_interval_s", "numwant" ] } }, "required": [ "revision", "degraded", "fail_closed", "device_id", "delivery_state", "qos", "instruction" ], "additionalProperties": true, "dependentRequired": { "tracker_state": [ "tracker_qos" ], "tracker_qos": [ "tracker_state" ] } }, "example": { "revision": 4, "degraded": false, "fail_closed": false, "device_id": "edge-01", "delivery_state": "pre-instructions", "qos": { "max_peers": { "value": 10, "source": "builtin" }, "per_peer_bps": { "value": 20000, "source": "global" }, "fanout": { "value": 1, "source": "builtin" }, "seed_up_bps": { "value": 20000, "source": "global", "derived_from": { "per_peer_bps": { "value": 20000, "source": "global" }, "fanout": { "value": 1, "source": "builtin" } } }, "seed_down_bps": { "value": 20000, "source": "global", "derived_from": { "per_peer_bps": { "value": 20000, "source": "global" }, "fanout": { "value": 1, "source": "builtin" } } }, "leech_up_bps": { "value": 20000, "source": "global", "derived_from": { "per_peer_bps": { "value": 20000, "source": "global" }, "fanout": { "value": 1, "source": "builtin" } } }, "leech_down_bps": { "value": 20000, "source": "global", "derived_from": { "per_peer_bps": { "value": 20000, "source": "global" }, "fanout": { "value": 1, "source": "builtin" } } }, "overall_up_bps": { "value": 0, "source": "builtin" }, "overall_down_bps": { "value": 0, "source": "builtin" }, "max_concurrent": { "value": 100, "source": "builtin" }, "request_peer_speed_limit_bps": { "value": 51200, "source": "builtin" }, "announce_min_interval_s": { "value": 30, "source": "builtin" }, "numwant": { "value": 50, "source": "builtin", "effective_ceiling": 50, "runtime_request_zero": "disabled", "constraint_source": "pinned-aria2-client" }, "handout_budget": { "value": 0, "source": "builtin" }, "catalog_tick_s": { "value": 60, "source": "builtin", "offline_horizon_s": 600, "heartbeat_always": true }, "telemetry_every_ticks": { "value": 1, "source": "builtin" }, "peer_telemetry_interval_s": { "value": 60, "source": "builtin" }, "telemetry_pause": { "value": false, "source": "builtin" }, "on_stale": { "value": "defaults", "source": "builtin" }, "origin_up_bps": { "value": 0, "source": "builtin" }, "origin_per_torrent_up_bps": { "value": 0, "source": "builtin" }, "origin_max_peers": { "value": 55, "source": "builtin" } }, "instruction": { "display_state": "applied", "label": "applied r9223372036854775807", "evidence": "agent-asserted", "underlying_state": "applied", "underlying_label": "applied r9223372036854775807", "underlying_evidence": "agent-asserted", "reason": null, "reported_instr_serial": 9223372036854775807, "accepted_identity": { "epoch": 11, "instr_serial": 9223372036854775807, "policy_revision": 7 }, "verify_level": "sig", "pointer_skew": false, "qos_drift_count": 0, "report_age_seconds": 3, "report_stale": false, "revoked": false, "revocation_evidence": "server-observed" }, "tracker_state": "seeder", "tracker_qos": { "announce_min_interval_s": { "value": 120, "source": "role-state:boat:seeder" }, "numwant": { "value": 4, "source": "global-state:seeder", "effective_ceiling": 4, "runtime_request_zero": "disabled", "constraint_source": "pinned-aria2-client" } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "400": { "description": "Invalid content length or Request body not supported", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "404": { "description": "Device not found or Route not found", "x-iris-problem-codes": [ "device_not_found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "device_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#device_not_found", "title": "Device not found", "status": 404, "code": "device_not_found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid policy request", "x-iris-problem-codes": [ "invalid_policy_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management api unavailable or Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API" } }, "/api/v1/peer-policy/explain": { "get": { "operationId": "console_get_api_v1_peer_policy_explain", "summary": "Explain mutual peer access", "description": "Explain mutual peer access. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "a", "in": "query", "required": true, "description": "Bare device ID, device:, or service:seeder. Requires one fresh, unambiguous durable IPv4 attribution; no inventory-IP fallback.", "schema": { "type": "string" }, "example": "edge-01" }, { "name": "b", "in": "query", "required": true, "description": "Bare device ID, device:, or service:seeder. Requires one fresh, unambiguous durable IPv4 attribution; no inventory-IP fallback.", "schema": { "type": "string" }, "example": "service:seeder" } ], "responses": { "200": { "description": "Explain mutual peer access response", "content": { "application/json": { "schema": { "title": "ConsolePeerPolicyExplainResponse", "type": "object", "properties": { "revision": { "type": "integer" }, "degraded": { "type": "boolean" }, "fail_closed": { "type": "boolean" }, "a": { "title": "ConsolePeerPolicyExplainResponseA", "type": "object", "properties": { "principal": { "title": "ConsolePeerPolicyExplainResponseAPrincipal", "type": "object", "properties": { "type": { "type": "string", "enum": [ "device", "service" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": true }, "role": { "type": [ "string", "null" ] }, "acl_source": { "type": "string" }, "acl_name": { "type": [ "string", "null" ] }, "decision": { "type": "string" }, "matched_seq": { "type": [ "integer", "null" ] }, "role_unknown": { "type": "boolean" }, "role_shadowed_by": { "type": [ "string", "null" ] } }, "required": [ "principal", "role", "acl_source", "acl_name", "decision", "matched_seq", "role_unknown", "role_shadowed_by" ], "additionalProperties": true }, "b": { "title": "ConsolePeerPolicyExplainResponseB", "type": "object", "properties": { "principal": { "title": "ConsolePeerPolicyExplainResponseBPrincipal", "type": "object", "properties": { "type": { "type": "string", "enum": [ "device", "service" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": true }, "role": { "type": [ "string", "null" ] }, "acl_source": { "type": "string" }, "acl_name": { "type": [ "string", "null" ] }, "decision": { "type": "string" }, "matched_seq": { "type": [ "integer", "null" ] }, "role_unknown": { "type": "boolean" }, "role_shadowed_by": { "type": [ "string", "null" ] } }, "required": [ "principal", "role", "acl_source", "acl_name", "decision", "matched_seq", "role_unknown", "role_shadowed_by" ], "additionalProperties": true }, "mutual": { "type": "boolean" } }, "required": [ "revision", "degraded", "fail_closed", "a", "b", "mutual" ], "additionalProperties": true }, "example": { "revision": 4, "degraded": false, "fail_closed": false, "a": { "principal": { "type": "device", "id": "edge-01" }, "role": "boat", "acl_source": "role:boat", "acl_name": "role:boat", "decision": "permit", "matched_seq": 10, "role_unknown": false, "role_shadowed_by": null }, "b": { "principal": { "type": "device", "id": "edge-02" }, "role": "boat", "acl_source": "role:boat", "acl_name": "role:boat", "decision": "permit", "matched_seq": 10, "role_unknown": false, "role_shadowed_by": null }, "mutual": true } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "400": { "description": "Invalid content length or Request body not supported", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Principal unresolvable", "x-iris-problem-codes": [ "principal_unresolvable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#principal_unresolvable", "title": "Principal unresolvable", "status": 422, "code": "principal_unresolvable" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management api unavailable or Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } } } }, "/api/v1/peer-policy/quarantine/{device_id}": { "put": { "operationId": "console_put_api_v1_peer_policy_quarantine_device_id", "summary": "Set device quarantine", "description": "Set device quarantine. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": false, "description": "Strong ETag from GET peer-policy. Body if_revision remains until the advertised Sunset for v1 clients.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Set device quarantine response", "content": { "application/json": { "schema": { "title": "ConsolePeerPolicyQuarantineDeviceIdResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "quarantined": { "type": "boolean" } }, "required": [ "ok", "revision", "quarantined" ], "additionalProperties": true }, "example": { "ok": true, "revision": 5, "quarantined": true } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-5\"" } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition-failed", "title": "Precondition failed", "status": 412, "code": "precondition-failed" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Unprocessable content", "x-iris-problem-codes": [ "unprocessable-content" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#unprocessable-content", "title": "Unprocessable content", "status": 422, "code": "unprocessable-content" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-compatibility": "Body if_revision is retained through 2027-09-04; omission emits Deprecation and Sunset.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsolePeerPolicyQuarantineDeviceIdRequest", "type": "object", "properties": { "quarantined": { "type": "boolean" }, "if_revision": { "type": "integer" } }, "required": [ "quarantined", "if_revision" ], "additionalProperties": true }, "example": { "quarantined": true, "if_revision": 4 } } } } } }, "/api/v1/audit": { "get": { "operationId": "console_get_api_v1_audit", "summary": "List audit events", "description": "List audit events. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque next_cursor from the previous page. Keep time/category filters unchanged. A 409 requires a fresh first page.", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "example": 200 }, { "name": "before_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788470400 }, { "name": "after_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788384000 }, { "name": "category", "in": "query", "required": false, "description": "Audit event category", "schema": { "type": "string" }, "example": "auth" } ], "responses": { "200": { "description": "List audit events response", "content": { "application/json": { "schema": { "title": "ConsoleAuditResponse", "type": "object", "properties": { "events": { "type": "array", "items": { "title": "ConsoleAuditResponseEventsItem", "type": "object", "properties": { "ts": { "type": "integer" }, "event": { "type": "string" }, "category": { "type": "string" }, "result": { "type": "string" } }, "required": [ "ts", "event", "result" ], "additionalProperties": true } }, "next_cursor": { "type": [ "string", "null" ], "maxLength": 256 } }, "required": [ "events", "next_cursor" ], "additionalProperties": true }, "example": { "events": [ { "ts": 1788470400, "event": "login", "category": "auth", "result": "ok" } ], "next_cursor": null } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/audit/histogram": { "get": { "operationId": "console_get_api_v1_audit_histogram", "summary": "Read audit histogram", "description": "Read audit histogram. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "example": "auth" }, { "name": "buckets", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "example": 30 }, { "name": "window", "in": "query", "required": false, "description": "Seconds ending at server now; ignored when both bounds are present", "schema": { "type": "number", "exclusiveMinimum": 0 }, "example": 604800 }, { "name": "since_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788384000 }, { "name": "until_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788470400 } ], "responses": { "200": { "description": "Read audit histogram response", "content": { "application/json": { "schema": { "title": "ConsoleAuditHistogramResponse", "type": "object", "properties": { "buckets": { "type": "array", "items": { "title": "ConsoleAuditHistogramResponseBucketsItem", "type": "object", "properties": { "start": { "type": "integer" }, "count": { "type": "integer" } }, "required": [ "start", "count" ], "additionalProperties": true } }, "now": { "type": "integer" }, "bucket_seconds": { "type": "integer" } }, "required": [ "buckets", "now", "bucket_seconds" ], "additionalProperties": true }, "example": { "buckets": [ { "start": 1788470400, "count": 1 } ], "now": 1788474000, "bucket_seconds": 120 } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/session": { "get": { "operationId": "console_get_api_v1_session", "summary": "Read console session", "description": "Read console session. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read console session response", "content": { "application/json": { "schema": { "title": "ConsoleSessionResponse", "type": "object", "properties": { "username": { "type": "string" }, "csrf": { "type": "string" } }, "required": [ "username", "csrf" ], "additionalProperties": true }, "example": { "username": "admin", "csrf": "session-csrf-token" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/settings/key-maintenance": { "get": { "operationId": "console_get_api_v1_settings_key_maintenance", "summary": "Read key maintenance policies and operations", "description": "Read key maintenance policies and operations. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read key maintenance policies and operations response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "const": 1 }, "revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "observed_at": { "type": [ "integer", "null" ] }, "worker": { "enum": [ "not-observed", "observed", "stale", "clock-error" ] }, "policies": { "type": "array", "maxItems": 32, "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "family": { "enum": [ "online-signer", "device-instruction", "management-token", "browser-tls", "management-tls", "device-tls", "peer-ca", "offline-roots", "age-identity", "seeder-token", "metrics-token", "collector-headers" ] }, "target": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "next_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "interval_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "window_minutes": { "type": "integer", "minimum": 5, "maximum": 1440 } }, "required": [ "id", "family", "target", "enabled", "next_at", "interval_days", "window_minutes" ], "additionalProperties": false } }, "jobs": { "type": "array", "maxItems": 256, "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "policy_id": { "type": "string", "format": "uuid" }, "family": { "enum": [ "online-signer", "device-instruction", "management-token", "browser-tls", "management-tls", "device-tls", "peer-ca", "offline-roots", "age-identity", "seeder-token", "metrics-token", "collector-headers" ] }, "target": { "type": "string" }, "state": { "enum": [ "approval-required", "cancelled", "completed", "intervention-required", "missed", "review-required", "reviewed", "running", "verification-required" ] }, "due_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "updated_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "detail": { "type": "string", "maxLength": 300 }, "before": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "after": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" } }, "required": [ "id", "policy_id", "family", "target", "state", "due_at", "updated_at", "detail", "before", "after" ], "additionalProperties": false } }, "families": { "type": "array", "items": { "type": "object", "properties": { "id": { "enum": [ "online-signer", "device-instruction", "management-token", "browser-tls", "management-tls", "device-tls", "peer-ca", "offline-roots", "age-identity", "seeder-token", "metrics-token", "collector-headers" ] }, "label": { "type": "string" }, "action": { "enum": [ "prepare", "rotate", "review" ] }, "requirement": { "type": "string" }, "guide": { "type": "string" } }, "required": [ "id", "label", "action", "requirement", "guide" ], "additionalProperties": false } }, "peer_leaf_renewal": { "type": "string" } }, "required": [ "schema", "revision", "observed_at", "worker", "policies", "jobs", "families", "peer_leaf_renewal" ], "additionalProperties": false }, "example": { "schema": 1, "revision": 0, "policies": [], "jobs": [], "observed_at": null, "worker": "not-observed", "families": [ { "id": "online-signer", "label": "Online instruction signer", "action": "prepare", "requirement": "Offline certificate and retirement approvals", "guide": "admin-guide/signer-rotation/" }, { "id": "device-instruction", "label": "Device instruction encryption key", "action": "rotate", "requirement": "Seven-day overlap; verify device acceptance", "guide": "admin-guide/rotations/#rotate-one-devices-instruction-key" }, { "id": "management-token", "label": "Console management credential", "action": "rotate", "requirement": "Verify all Console instances before retiring overlap", "guide": "admin-guide/rotations/#rotate-the-management-credential" }, { "id": "browser-tls", "label": "Console browser TLS", "action": "review", "requirement": "Public request, approval and listener verification in Certificates & keys", "guide": "admin-guide/console-credentials/#replace-the-browser-certificate" }, { "id": "management-tls", "label": "Management TLS", "action": "review", "requirement": "Stage Console trust, replace server pair, verify listeners", "guide": "admin-guide/rotations/#rotate-the-management-certificate" }, { "id": "device-tls", "label": "Device-pinned TLS", "action": "review", "requirement": "Device trust rollout and re-onboarding", "guide": "admin-guide/rotations/#rotate-the-certificate-that-devices-trust" }, { "id": "peer-ca", "label": "Private swarm issuing CA", "action": "review", "requirement": "Coordinated trust rollout; distinct from automatic leaf renewal", "guide": "admin-guide/rotations/" }, { "id": "offline-roots", "label": "Offline signing roots", "action": "review", "requirement": "Independent custodians and device trust rollout", "guide": "admin-guide/instruction-keys/" }, { "id": "age-identity", "label": "Encryption-at-rest identity and recipients", "action": "review", "requirement": "Protected backup, stopped writers and decryption proof", "guide": "admin-guide/rotations/#rotate-the-age-recipients" }, { "id": "seeder-token", "label": "Seeder announce credential", "action": "review", "requirement": "Maintenance freeze and tracker serving proof", "guide": "admin-guide/rotations/#rotate-the-seeder-announce-credential" }, { "id": "metrics-token", "label": "Metrics scrape credential", "action": "review", "requirement": "Console replacement, scraper migration and verified retirement", "guide": "admin-guide/console-credentials/#replace-the-metrics-scraping-token" }, { "id": "collector-headers", "label": "Outbound telemetry credentials", "action": "review", "requirement": "Console replacement, collector approval and delivery proof", "guide": "admin-guide/console-credentials/#replace-outbound-collector-authentication" } ], "peer_leaf_renewal": "Device-managed; one-day certificates renew six hours before expiry." } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "console_post_api_v1_settings_key_maintenance", "summary": "Configure or approve key maintenance", "description": "Configure or approve key maintenance. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Configure or approve key maintenance response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "const": 1 }, "revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "observed_at": { "type": [ "integer", "null" ] }, "worker": { "enum": [ "not-observed", "observed", "stale", "clock-error" ] }, "policies": { "type": "array", "maxItems": 32, "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "family": { "enum": [ "online-signer", "device-instruction", "management-token", "browser-tls", "management-tls", "device-tls", "peer-ca", "offline-roots", "age-identity", "seeder-token", "metrics-token", "collector-headers" ] }, "target": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "next_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "interval_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "window_minutes": { "type": "integer", "minimum": 5, "maximum": 1440 } }, "required": [ "id", "family", "target", "enabled", "next_at", "interval_days", "window_minutes" ], "additionalProperties": false } }, "jobs": { "type": "array", "maxItems": 256, "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "policy_id": { "type": "string", "format": "uuid" }, "family": { "enum": [ "online-signer", "device-instruction", "management-token", "browser-tls", "management-tls", "device-tls", "peer-ca", "offline-roots", "age-identity", "seeder-token", "metrics-token", "collector-headers" ] }, "target": { "type": "string" }, "state": { "enum": [ "approval-required", "cancelled", "completed", "intervention-required", "missed", "review-required", "reviewed", "running", "verification-required" ] }, "due_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "updated_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "detail": { "type": "string", "maxLength": 300 }, "before": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "after": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" } }, "required": [ "id", "policy_id", "family", "target", "state", "due_at", "updated_at", "detail", "before", "after" ], "additionalProperties": false } }, "families": { "type": "array", "items": { "type": "object", "properties": { "id": { "enum": [ "online-signer", "device-instruction", "management-token", "browser-tls", "management-tls", "device-tls", "peer-ca", "offline-roots", "age-identity", "seeder-token", "metrics-token", "collector-headers" ] }, "label": { "type": "string" }, "action": { "enum": [ "prepare", "rotate", "review" ] }, "requirement": { "type": "string" }, "guide": { "type": "string" } }, "required": [ "id", "label", "action", "requirement", "guide" ], "additionalProperties": false } }, "peer_leaf_renewal": { "type": "string" } }, "required": [ "schema", "revision", "observed_at", "worker", "policies", "jobs", "families", "peer_leaf_renewal" ], "additionalProperties": false }, "example": { "schema": 1, "revision": 0, "policies": [], "jobs": [], "observed_at": null, "worker": "not-observed", "families": [ { "id": "online-signer", "label": "Online instruction signer", "action": "prepare", "requirement": "Offline certificate and retirement approvals", "guide": "admin-guide/signer-rotation/" }, { "id": "device-instruction", "label": "Device instruction encryption key", "action": "rotate", "requirement": "Seven-day overlap; verify device acceptance", "guide": "admin-guide/rotations/#rotate-one-devices-instruction-key" }, { "id": "management-token", "label": "Console management credential", "action": "rotate", "requirement": "Verify all Console instances before retiring overlap", "guide": "admin-guide/rotations/#rotate-the-management-credential" }, { "id": "browser-tls", "label": "Console browser TLS", "action": "review", "requirement": "Public request, approval and listener verification in Certificates & keys", "guide": "admin-guide/console-credentials/#replace-the-browser-certificate" }, { "id": "management-tls", "label": "Management TLS", "action": "review", "requirement": "Stage Console trust, replace server pair, verify listeners", "guide": "admin-guide/rotations/#rotate-the-management-certificate" }, { "id": "device-tls", "label": "Device-pinned TLS", "action": "review", "requirement": "Device trust rollout and re-onboarding", "guide": "admin-guide/rotations/#rotate-the-certificate-that-devices-trust" }, { "id": "peer-ca", "label": "Private swarm issuing CA", "action": "review", "requirement": "Coordinated trust rollout; distinct from automatic leaf renewal", "guide": "admin-guide/rotations/" }, { "id": "offline-roots", "label": "Offline signing roots", "action": "review", "requirement": "Independent custodians and device trust rollout", "guide": "admin-guide/instruction-keys/" }, { "id": "age-identity", "label": "Encryption-at-rest identity and recipients", "action": "review", "requirement": "Protected backup, stopped writers and decryption proof", "guide": "admin-guide/rotations/#rotate-the-age-recipients" }, { "id": "seeder-token", "label": "Seeder announce credential", "action": "review", "requirement": "Maintenance freeze and tracker serving proof", "guide": "admin-guide/rotations/#rotate-the-seeder-announce-credential" }, { "id": "metrics-token", "label": "Metrics scrape credential", "action": "review", "requirement": "Console replacement, scraper migration and verified retirement", "guide": "admin-guide/console-credentials/#replace-the-metrics-scraping-token" }, { "id": "collector-headers", "label": "Outbound telemetry credentials", "action": "review", "requirement": "Console replacement, collector approval and delivery proof", "guide": "admin-guide/console-credentials/#replace-outbound-collector-authentication" } ], "peer_leaf_renewal": "Device-managed; one-day certificates renew six hours before expiry." } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "const": "save-policy" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "policy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "family": { "enum": [ "online-signer", "device-instruction", "management-token", "browser-tls", "management-tls", "device-tls", "peer-ca", "offline-roots", "age-identity", "seeder-token", "metrics-token", "collector-headers" ] }, "target": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "next_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "interval_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "window_minutes": { "type": "integer", "minimum": 5, "maximum": 1440 } }, "required": [ "id", "family", "target", "enabled", "next_at", "interval_days", "window_minutes" ], "additionalProperties": false } }, "required": [ "action", "revision", "policy" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "enum": [ "retry", "reviewed", "retire-management", "reconcile-management" ] }, "job_id": { "type": "string", "format": "uuid" }, "confirm": { "const": true } }, "required": [ "action", "job_id", "confirm" ], "additionalProperties": false } ] }, "example": { "action": "save-policy", "revision": 0, "policy": { "id": "00000000-0000-0000-0000-000000000001", "family": "online-signer", "target": "deployment", "enabled": false, "next_at": 1790294400, "interval_days": 14, "window_minutes": 30 } } } } } } }, "/api/v1/login": { "post": { "operationId": "console_post_api_v1_login", "summary": "Create console session", "description": "Create console session. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consolePassword", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consolePassword": [] } ], "parameters": [], "responses": { "200": { "description": "Session credentials, or a one-use setup grant before the first administrator exists", "headers": { "Set-Cookie": { "description": "Present only for a configured administrator login", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "ConsoleLoginSession", "type": "object", "properties": { "username": { "type": "string" }, "csrf": { "type": "string" } }, "required": [ "username", "csrf" ], "additionalProperties": false }, { "title": "ConsoleLoginSetupGrant", "type": "object", "properties": { "setup": { "type": "boolean" }, "setup_grant": { "type": "string" } }, "required": [ "setup", "setup_grant" ], "additionalProperties": false } ] }, "examples": { "configured": { "value": { "username": "admin", "csrf": "session-csrf-token" } }, "firstRun": { "value": { "setup": true, "setup_grant": "short-lived-one-time-grant" } } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Authentication required", "x-iris-problem-codes": [ "authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#authentication-required", "title": "Authentication required", "status": 401, "code": "authentication-required" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleLoginRequest", "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string", "format": "password", "writeOnly": true } }, "required": [ "username", "password" ], "additionalProperties": false }, "example": { "username": "admin", "password": "operator-entered-password" } } } } } }, "/api/v1/setup": { "post": { "operationId": "console_post_api_v1_setup", "summary": "Create the first administrator", "description": "Create the first administrator. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "setupGrant", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "setupGrant": [] } ], "parameters": [], "responses": { "200": { "description": "Create the first administrator response", "content": { "application/json": { "schema": { "title": "ConsoleSetupResponse", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "403": { "description": "Forbidden", "x-iris-problem-codes": [ "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "415": { "description": "Unsupported media type", "x-iris-problem-codes": [ "unsupported-media-type" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#unsupported-media-type", "title": "Unsupported media type", "status": 415, "code": "unsupported-media-type" } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleSetupRequest", "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string", "format": "password", "writeOnly": true }, "setup_grant": { "type": "string", "writeOnly": true } }, "required": [ "username", "password", "setup_grant" ], "additionalProperties": false }, "example": { "username": "admin", "password": "new-administrator-password", "setup_grant": "short-lived-one-time-grant" } } } } } }, "/api/v1/logout": { "post": { "operationId": "console_post_api_v1_logout", "summary": "End console session", "description": "End console session. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "End console session response", "content": { "application/json": { "schema": { "title": "ConsoleLogoutResponse", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleLogoutRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/api/v1/images": { "get": { "operationId": "console_get_api_v1_images", "summary": "List images", "description": "List images. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. This bounded v1 collection has no pagination parameter; adding one without a stable compatibility shape is deferred to the next major version.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "List images response", "content": { "application/json": { "schema": { "title": "ConsoleImagesResponse", "type": "object", "properties": { "images": { "type": "array", "items": { "title": "ConsoleImagesResponseImagesItem", "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer" }, "sha256": { "type": "string" } }, "required": [ "id", "filename", "size", "sha256" ], "additionalProperties": true } } }, "required": [ "images" ], "additionalProperties": true }, "example": { "images": [ { "id": "image-01", "filename": "image.bin", "size": 1048576, "sha256": "0000000000000000000000000000000000000000000000000000000000000000" } ] } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/images/importable": { "get": { "operationId": "console_get_api_v1_images_importable", "summary": "List importable images", "description": "List importable images. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "List importable images response", "content": { "application/json": { "schema": { "title": "ConsoleImagesImportableResponse", "type": "object", "properties": { "importable": { "type": "array", "items": { "title": "ConsoleImagesImportableResponseImportableItem", "type": "object", "properties": { "path": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer" } }, "required": [ "path", "filename", "size" ], "additionalProperties": true } }, "skipped": { "type": "array", "items": { "type": "string" } } }, "required": [ "importable", "skipped" ], "additionalProperties": true }, "example": { "importable": [ { "path": "/srv/images/ios-xe/image.bin", "filename": "image.bin", "size": 1048576 } ], "skipped": [] } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/images/import": { "post": { "operationId": "console_post_api_v1_images_import", "summary": "Import an image", "description": "Import an image. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. image lifecycle action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Import an image response", "content": { "application/json": { "schema": { "title": "ConsoleImagesImportResponse", "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ], "additionalProperties": true }, "example": { "job_id": "job-01" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "image lifecycle action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleImagesImportRequest", "type": "object", "properties": { "path": { "type": "string" } }, "required": [ "path" ], "additionalProperties": true }, "example": { "path": "/srv/images/ios-xe/example.bin" } } } } } }, "/api/v1/images/upload/{filename}": { "put": { "operationId": "console_put_api_v1_images_upload_filename", "summary": "Upload an image", "description": "Upload an image. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "filename", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Upload an image response", "content": { "application/json": { "schema": { "title": "ConsoleImagesUploadFilenameResponse", "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ], "additionalProperties": true }, "example": { "job_id": "job-01" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "408": { "description": "Request timeout", "x-iris-problem-codes": [ "request-timeout" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-timeout", "title": "Request timeout", "status": 408, "code": "request-timeout" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": {}, "example": "" } } } } }, "/api/v1/images/jobs/{job_id}": { "get": { "operationId": "console_get_api_v1_images_jobs_job_id", "summary": "Read image job", "description": "Read image job. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" } ], "responses": { "200": { "description": "Current publish phase and, after the durable publish, the Cisco Bulk Hash reconciliation result", "content": { "application/json": { "schema": { "oneOf": [ { "title": "ConsoleImagesJobsJobIdResponsePublishing", "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "message": { "type": "string" }, "started_at": { "type": "integer" }, "state": { "type": "string", "const": "publishing" }, "image_id": { "type": "null" }, "finished_at": { "type": "null" }, "verification": { "type": "null" } }, "required": [ "id", "state", "filename", "message", "image_id", "started_at", "finished_at", "verification" ], "additionalProperties": true }, { "title": "ConsoleImagesJobsJobIdResponseVerifying", "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "message": { "type": "string" }, "started_at": { "type": "integer" }, "state": { "type": "string", "const": "verifying" }, "image_id": { "type": "string" }, "finished_at": { "type": "null" }, "verification": { "title": "ConsoleImagesJobsJobIdResponseVerificationRunning", "type": "object", "properties": { "outcome": { "type": "string", "const": "running" }, "image_state": { "type": [ "string", "null" ], "enum": [ "verified", "mismatch", "not_in_feed", null ] } }, "required": [ "outcome", "image_state" ], "additionalProperties": false } }, "required": [ "id", "state", "filename", "message", "image_id", "started_at", "finished_at", "verification" ], "additionalProperties": true }, { "title": "ConsoleImagesJobsJobIdResponseDone", "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "message": { "type": "string" }, "started_at": { "type": "integer" }, "state": { "type": "string", "const": "done" }, "image_id": { "type": "string" }, "finished_at": { "type": "integer" }, "verification": { "oneOf": [ { "title": "ConsoleImagesJobsJobIdResponseVerificationSuccess", "type": "object", "properties": { "outcome": { "type": "string", "const": "ok" }, "image_state": { "type": [ "string", "null" ], "enum": [ "verified", "mismatch", "not_in_feed", null ] }, "matched": { "type": [ "integer", "null" ], "minimum": 0 }, "mismatched": { "type": [ "integer", "null" ], "minimum": 0 }, "not_in_feed": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "outcome", "image_state", "matched", "mismatched", "not_in_feed" ], "additionalProperties": false }, { "title": "ConsoleImagesJobsJobIdResponseVerificationFailure", "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "fail", "already_running" ] }, "image_state": { "type": [ "string", "null" ], "enum": [ "verified", "mismatch", "not_in_feed", null ] }, "detail": { "type": "string" } }, "required": [ "outcome", "image_state", "detail" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "state", "filename", "message", "image_id", "started_at", "finished_at", "verification" ], "additionalProperties": true }, { "title": "ConsoleImagesJobsJobIdResponseError", "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "message": { "type": "string" }, "started_at": { "type": "integer" }, "state": { "type": "string", "const": "error" }, "image_id": { "type": [ "string", "null" ] }, "finished_at": { "type": "integer" }, "verification": { "type": "null" } }, "required": [ "id", "state", "filename", "message", "image_id", "started_at", "finished_at", "verification" ], "additionalProperties": true } ] }, "examples": { "publishing": { "value": { "id": "job-01", "state": "publishing", "filename": "image.bin", "message": "", "image_id": null, "started_at": 1788470400, "finished_at": null, "verification": null } }, "verifying": { "value": { "id": "job-01", "state": "verifying", "filename": "image.bin", "message": "", "image_id": "image-01", "started_at": 1788470400, "finished_at": null, "verification": { "outcome": "running", "image_state": null } } }, "verified": { "value": { "id": "job-01", "state": "done", "filename": "image.bin", "message": "", "image_id": "image-01", "started_at": 1788470400, "finished_at": 1788470412, "verification": { "outcome": "ok", "image_state": "verified", "matched": 1, "mismatched": 0, "not_in_feed": 0 } } }, "verificationFailed": { "value": { "id": "job-01", "state": "done", "filename": "image.bin", "message": "published, but Cisco hash verification did not complete", "image_id": "image-01", "started_at": 1788470400, "finished_at": 1788470412, "verification": { "outcome": "fail", "image_state": null, "detail": "feed unavailable" } } }, "publishFailed": { "value": { "id": "job-01", "state": "error", "filename": "image.bin", "message": "publish failed", "image_id": null, "started_at": 1788470400, "finished_at": 1788470401, "verification": null } } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/images/{image_id}": { "delete": { "operationId": "console_delete_api_v1_images_image_id", "summary": "Delete an image", "description": "Delete an image. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "image_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Delete an image response", "content": { "application/json": { "schema": { "title": "ConsoleImagesImageIdResponse", "type": "object", "properties": { "deleted": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "deleted", "warnings" ], "additionalProperties": true }, "example": { "deleted": true, "warnings": [] } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/images/{image_id}/release-quarantine": { "post": { "operationId": "console_post_api_v1_images_image_id_release_quarantine", "summary": "Release image quarantine", "description": "Release image quarantine. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. image lifecycle action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "image_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Release image quarantine response", "content": { "application/json": { "schema": { "title": "ConsoleImagesImageIdReleaseQuarantineResponse", "type": "object", "properties": { "released": { "type": "boolean" }, "override": { "type": "boolean" }, "state": { "type": "string" }, "seeding_resumed": { "type": "boolean" } }, "required": [ "released", "override", "state", "seeding_resumed" ], "additionalProperties": true }, "example": { "released": true, "override": false, "state": "verified", "seeding_resumed": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "image lifecycle action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleImagesImageIdReleaseQuarantineRequest", "type": "object", "properties": { "override": { "type": "boolean" }, "confirm_text": { "type": "string" } }, "required": [], "additionalProperties": true }, "example": { "override": false, "confirm_text": "" } } } } } }, "/api/v1/image-verification/offline": { "post": { "operationId": "console_post_api_v1_image_verification_offline", "summary": "Upload offline verification data", "description": "Upload offline verification data. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. verification job action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Upload offline verification data response", "content": { "application/json": { "schema": { "title": "ConsoleImageVerificationOfflineResponse", "type": "object", "properties": { "outcome": { "type": "string" }, "matched": { "type": "integer" }, "mismatched": { "type": "integer" }, "not_in_feed": { "type": "integer" } }, "required": [ "outcome", "matched", "mismatched", "not_in_feed" ], "additionalProperties": true }, "example": { "outcome": "ok", "matched": 1, "mismatched": 0, "not_in_feed": 0 } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "408": { "description": "Request timeout", "x-iris-problem-codes": [ "request-timeout" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-timeout", "title": "Request timeout", "status": 408, "code": "request-timeout" } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "502": { "description": "Upstream operation failed", "x-iris-problem-codes": [ "upstream-operation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#upstream-operation-failed", "title": "Upstream operation failed", "status": 502, "code": "upstream-operation-failed" } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "verification job action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": {}, "example": "" } } } } }, "/api/v1/image-verification/refresh": { "post": { "operationId": "console_post_api_v1_image_verification_refresh", "summary": "Start image verification refresh", "description": "Start image verification refresh. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. verification job action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Start image verification refresh response", "content": { "application/json": { "schema": { "title": "ConsoleImageVerificationRefreshResponse", "type": "object", "properties": { "outcome": { "type": "string" }, "matched": { "type": "integer" }, "mismatched": { "type": "integer" }, "not_in_feed": { "type": "integer" } }, "required": [ "outcome", "matched", "mismatched", "not_in_feed" ], "additionalProperties": true }, "example": { "outcome": "ok", "matched": 1, "mismatched": 0, "not_in_feed": 0 } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "502": { "description": "Upstream operation failed", "x-iris-problem-codes": [ "upstream-operation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#upstream-operation-failed", "title": "Upstream operation failed", "status": 502, "code": "upstream-operation-failed" } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "verification job action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleImageVerificationRefreshRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/api/v1/devices": { "get": { "operationId": "console_get_api_v1_devices", "summary": "List devices", "description": "List devices. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Status filter keys remain stable: deployed displays as Staged, placement-failed as Staging failed, and waiting-staging means an assigned device has not reported work on the current set. Current per-image errors take precedence over earlier staged flags.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size; omit for the v1 whole-fleet compatibility response", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "example": 100 }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset; paged results sort by device_id", "schema": { "type": "integer", "minimum": 0 }, "example": 0 }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive device search", "schema": { "type": "string" }, "example": "edge" }, { "name": "management_type", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "routed", "inband", "router-routed", "router-nat", "xr-host", "legacy" ] }, "example": "inband" }, { "name": "platform", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "guestshell", "iox", "router", "xr-appmgr", "__none" ] }, "example": "iox" }, { "name": "cred", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string" }, "example": "default" }, { "name": "telemetry", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "on", "off", "unknown" ] }, "example": "on" }, { "name": "peer", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "quarantined", "not-quarantined" ] }, "example": "not-quarantined" }, { "name": "role", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string" }, "example": "boat" }, { "name": "model_family", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "IE3x00", "IR1x00", "C9xxx", "C8xxx", "ISR/ASR/CSR", "XR8000", "NCS", "unknown" ] }, "example": "C9xxx" }, { "name": "os_family", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "xe", "xr" ] }, "example": "xe" }, { "name": "status", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "onboarding", "undeploying", "waiting-heartbeat", "waiting-staging", "onboard-failed", "undeploy-failed", "deployed", "placement-failed", "image-failed", "copying", "staging", "unassigned", "enrolled", "not-enrolled", "offline", "__attention" ] }, "example": "deployed" } ], "responses": { "200": { "description": "List devices response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesResponse", "type": "object", "properties": { "devices": { "type": "array", "items": { "title": "ConsoleDevicesResponseDevicesItem", "type": "object", "properties": { "device_id": { "type": "string" }, "device_ip": { "type": "string" }, "model_family": { "type": "string" }, "os_family": { "type": "string" }, "platform_resolved": { "type": "string" }, "instruction": { "type": "object", "properties": { "display_state": { "type": "string", "enum": [ "applied", "lkg", "stale", "rejected", "tracker-only", "pre-instructions", "unknown", "unavailable", "pending", "forbidden", "floor_reset", "none", "revoked" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 96 }, "evidence": { "type": "string", "enum": [ "agent-asserted", "server-observed" ] }, "underlying_state": { "type": [ "string", "null" ], "enum": [ "allowlist_expired", "applied", "audience_mismatch", "floor_reset", "instr_forbidden", "instr_pending", "instr_unavailable", "key_rejected", "lkg", "lkg_rejected", "lkg_unreadable", "none", "oversize", "reasserted", "rollback_rejected", "stale_expired", "tamper_rejected", "tracker-only", "verifier_missing", null ] }, "underlying_label": { "type": "string", "minLength": 1, "maxLength": 96 }, "underlying_evidence": { "type": "string", "const": "agent-asserted" }, "reason": { "type": [ "string", "null" ], "enum": [ "bad_mac", "unknown_key", null ] }, "reported_instr_serial": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "accepted_identity": { "oneOf": [ { "type": "object", "required": [ "epoch", "instr_serial", "policy_revision" ], "additionalProperties": false, "properties": { "epoch": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "instr_serial": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "policy_revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } } }, { "type": "null" } ], "description": "Complete accepted-envelope identity asserted by the agent. Null means no complete accepted identity was reported." }, "verify_level": { "type": [ "string", "null" ], "enum": [ "sig", "none", null ] }, "pointer_skew": { "type": [ "boolean", "null" ] }, "qos_drift_count": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 49 }, "report_age_seconds": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "report_stale": { "type": [ "boolean", "null" ] }, "revoked": { "type": [ "boolean", "null" ] }, "revocation_evidence": { "type": "string", "const": "server-observed" } }, "required": [ "display_state", "label", "evidence", "underlying_state", "underlying_label", "underlying_evidence", "reason", "reported_instr_serial", "accepted_identity", "verify_level", "pointer_skew", "qos_drift_count", "report_age_seconds", "report_stale", "revoked", "revocation_evidence" ], "additionalProperties": false, "description": "Canonical bounded instruction display projection. Device facts remain assertions; server-observed revocation and report age may take display precedence while retaining the underlying report." }, "peer_tls": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "configured_mode", "runtime_mode", "runtime_source" ], "properties": { "configured_mode": { "enum": [ "disabled", "required" ] }, "runtime_mode": { "enum": [ "disabled", "required", "unknown" ] }, "runtime_source": { "enum": [ "aria2_rpc", "unknown" ] }, "revocations": { "type": "object", "properties": { "supported": { "const": true }, "mode": { "enum": [ "required", "disabled" ] }, "state": { "enum": [ "valid", "unavailable", "expired" ] }, "authority": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "issued_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "expires_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "own_revoked": { "type": "boolean" }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "supported", "mode", "state", "authority", "revision", "issued_at", "expires_at", "own_revoked", "observed_at" ], "additionalProperties": false } }, "description": "Last reported torrent TLS daemon policy, not negotiated connection evidence. Missing means unknown." }, { "type": "null" } ] } }, "required": [ "device_id", "device_ip", "model_family", "os_family", "platform_resolved", "instruction" ], "additionalProperties": true } }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "revision": { "type": "integer" }, "now": { "type": "integer" }, "target_facts": { "title": "ConsoleDevicesResponseTarget_Facts", "type": "object", "properties": { "missing_os_family": { "type": "integer" }, "role_drift": { "type": "integer" } }, "required": [ "missing_os_family", "role_drift" ], "additionalProperties": true }, "target_warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "devices", "total", "offset", "limit", "revision", "now", "target_facts", "target_warnings" ], "additionalProperties": true }, "example": { "devices": [ { "device_id": "edge-01", "device_ip": "192.0.2.10", "model_family": "C9xxx", "os_family": "xe", "platform_resolved": "guestshell", "instruction": { "display_state": "applied", "label": "applied r9223372036854775807", "evidence": "agent-asserted", "underlying_state": "applied", "underlying_label": "applied r9223372036854775807", "underlying_evidence": "agent-asserted", "reason": null, "reported_instr_serial": 9223372036854775807, "accepted_identity": { "epoch": 11, "instr_serial": 9223372036854775807, "policy_revision": 7 }, "verify_level": "sig", "pointer_skew": false, "qos_drift_count": 0, "report_age_seconds": 3, "report_stale": false, "revoked": false, "revocation_evidence": "server-observed" } } ], "total": 1, "offset": 0, "limit": null, "revision": 7, "now": 1788470400, "target_facts": { "missing_os_family": 0, "role_drift": 0 }, "target_warnings": [] } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-fleet-7\"" } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Device status temporarily busy or Service unavailable or Management API unavailable", "x-iris-problem-codes": [ "projection-busy", "service-unavailable", "management-api-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "projection-busy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#projection-busy", "title": "Device status temporarily busy", "status": 503, "code": "projection-busy" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } }, "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "console_post_api_v1_devices", "summary": "Create a device", "description": "Create a device. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size; omit for the v1 whole-fleet compatibility response", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "example": 100 }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset; paged results sort by device_id", "schema": { "type": "integer", "minimum": 0 }, "example": 0 }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive device search", "schema": { "type": "string" }, "example": "edge" }, { "name": "management_type", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "routed", "inband", "router-routed", "router-nat", "xr-host", "legacy" ] }, "example": "inband" }, { "name": "platform", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "guestshell", "iox", "router", "xr-appmgr", "__none" ] }, "example": "iox" }, { "name": "cred", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string" }, "example": "default" }, { "name": "telemetry", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "on", "off", "unknown" ] }, "example": "on" }, { "name": "peer", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "quarantined", "not-quarantined" ] }, "example": "not-quarantined" }, { "name": "role", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string" }, "example": "boat" }, { "name": "model_family", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "IE3x00", "IR1x00", "C9xxx", "C8xxx", "ISR/ASR/CSR", "XR8000", "NCS", "unknown" ] }, "example": "C9xxx" }, { "name": "os_family", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "xe", "xr" ] }, "example": "xe" }, { "name": "status", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "onboarding", "undeploying", "waiting-heartbeat", "waiting-staging", "onboard-failed", "undeploy-failed", "deployed", "placement-failed", "image-failed", "copying", "staging", "unassigned", "enrolled", "not-enrolled", "offline", "__attention" ] }, "example": "deployed" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Create a device response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesResponse", "type": "object", "properties": { "device": { "title": "ConsoleDevicesResponseDevice", "type": "object", "properties": { "device_id": { "type": "string" }, "device_ip": { "type": "string" }, "management_type": { "type": "string" } }, "required": [ "device_id", "device_ip", "management_type" ], "additionalProperties": true } }, "required": [ "device" ], "additionalProperties": true }, "example": { "device": { "device_id": "edge-01", "device_ip": "192.0.2.10", "management_type": "inband" } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Unprocessable content", "x-iris-problem-codes": [ "unprocessable-content" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#unprocessable-content", "title": "Unprocessable content", "status": 422, "code": "unprocessable-content" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleDevicesRequest", "type": "object", "properties": { "device_id": { "type": "string" }, "device_ip": { "type": "string" }, "management_type": { "type": "string", "enum": [ "routed", "inband", "router-routed", "router-nat", "xr-host" ] }, "model": { "type": "string" }, "credential_profile_id": { "type": "string" }, "iris_vlan": { "type": [ "string", "integer" ] }, "svi_ip": { "type": [ "string", "integer" ] }, "svi_mask": { "type": [ "string", "integer" ] }, "app_ip": { "type": [ "string", "integer" ] }, "app_mask": { "type": [ "string", "integer" ] }, "app_gateway": { "type": [ "string", "integer" ] }, "inband_vlan": { "type": [ "string", "integer" ] }, "ios_ssh_host": { "type": [ "string", "integer" ] }, "vpg_number": { "type": [ "string", "integer" ] }, "nat_interface": { "type": [ "string", "integer" ] }, "svi_igp": { "type": [ "string", "integer" ] }, "role": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "integer" ], "enum": [ "", "guestshell", "iox", "router", "xr-appmgr" ] } }, "required": [ "device_id", "device_ip", "management_type" ], "additionalProperties": false, "description": "Closed operator-owned fleet record. Unknown fields and the server-owned schema_version, registered_at, registration_id and os_family fields are rejected with 422." }, "example": { "device_id": "edge-01", "device_ip": "192.0.2.10", "management_type": "inband", "model": "C9300-48P", "credential_profile_id": "default" } } } } } }, "/api/v1/devices/{device_id}": { "delete": { "operationId": "console_delete_api_v1_devices_device_id", "summary": "Retire a device", "description": "Retire a device. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Retire a device response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdResponse", "type": "object", "properties": { "deleted": { "type": "boolean" }, "degraded": { "type": "array", "items": { "type": "string" } } }, "required": [ "deleted", "degraded" ], "additionalProperties": true }, "example": { "deleted": true, "degraded": [] } } } }, "207": { "description": "Device retired but one or more non-authorizing cleanup steps degraded", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdPartialResponse", "type": "object", "properties": { "deleted": { "type": "boolean" }, "degraded": { "type": "array", "items": { "type": "string" } } }, "required": [ "deleted", "degraded" ], "additionalProperties": true }, "example": { "deleted": true, "degraded": [] } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/devices/export-csv": { "get": { "operationId": "console_get_api_v1_devices_export_csv", "summary": "Export devices", "description": "Export devices. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "CSV document", "content": { "text/csv": { "schema": { "type": "string" }, "example": "device_id,device_ip\n" } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/devices/example-csv": { "get": { "operationId": "console_get_api_v1_devices_example_csv", "summary": "Download example device CSV", "description": "Download example device CSV. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "CSV document", "content": { "text/csv": { "schema": { "type": "string" }, "example": "device_id,device_ip\n" } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/devices/import-csv": { "post": { "operationId": "console_post_api_v1_devices_import_csv", "summary": "Import devices", "description": "Import devices. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. fleet batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Import devices response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesImportCsvResponse", "type": "object", "properties": { "imported": { "type": "integer" }, "new": { "type": "integer" }, "updated": { "type": "integer" }, "skipped": { "type": "integer" } }, "required": [ "imported", "new", "updated", "skipped" ], "additionalProperties": true }, "example": { "imported": 1, "new": 1, "updated": 0, "skipped": 0 } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "fleet batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "text/csv": { "schema": { "type": "string" }, "example": "device_id,device_ip\nedge-01,192.0.2.10\n" } } } } }, "/api/v1/devices/bulk-credential": { "post": { "operationId": "console_post_api_v1_devices_bulk_credential", "summary": "Assign credentials in bulk", "description": "Assign credentials in bulk. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. fleet batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Assign credentials in bulk response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesBulkCredentialResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "applied": { "type": "integer" }, "failed": { "title": "ConsoleDevicesBulkCredentialResponseFailed", "type": "object", "properties": {}, "required": [], "additionalProperties": true } }, "required": [ "ok", "applied", "failed" ], "additionalProperties": true }, "example": { "ok": true, "applied": 1, "failed": {} } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "fleet batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleDevicesBulkCredentialRequest", "type": "object", "properties": { "device_ids": { "type": "array", "items": { "type": "string" } }, "credential_profile_id": { "type": "string" } }, "required": [ "device_ids", "credential_profile_id" ], "additionalProperties": true }, "example": { "device_ids": [ "edge-01" ], "credential_profile_id": "default" } } } } } }, "/api/v1/devices/{device_id}/plan": { "get": { "operationId": "console_get_api_v1_devices_device_id_plan", "summary": "Read device plan", "description": "Read device plan. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" } ], "responses": { "200": { "description": "Read device plan response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdPlanResponse", "type": "object", "properties": { "plan": { "title": "ConsoleDevicesDeviceIdPlanResponsePlan", "type": "object", "properties": { "plan_hash": { "type": "string" }, "resolved": { "title": "ConsoleDevicesDeviceIdPlanResponsePlanResolved", "type": "object", "properties": { "platform": { "type": "string" }, "management_type": { "type": "string" } }, "required": [ "platform", "management_type" ], "additionalProperties": true } }, "required": [ "plan_hash", "resolved" ], "additionalProperties": true } }, "required": [ "plan" ], "additionalProperties": true }, "example": { "plan": { "plan_hash": "sha256:example", "resolved": { "platform": "iox", "management_type": "inband" } } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/devices/{device_id}/reports": { "get": { "operationId": "console_get_api_v1_devices_device_id_reports", "summary": "List device reports", "description": "List device reports. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" } ], "responses": { "200": { "description": "List device reports response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdReportsResponse", "type": "object", "properties": { "device_id": { "type": "string" }, "observed_at": { "type": "number" }, "pending_request": { "oneOf": [ { "type": "object", "properties": { "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "requested_at": { "type": "number", "minimum": 0 }, "expires_at": { "type": "number", "minimum": 0 } }, "required": [ "request_id", "requested_at", "expires_at" ], "additionalProperties": false }, { "type": "null" } ] }, "reports": { "type": "array", "items": { "oneOf": [ { "title": "ConsoleDevicesDeviceIdReportsResponseV2Report", "type": "object", "properties": { "v": { "type": "integer" }, "schema": { "type": "string", "const": "v2" }, "report_id": { "type": "string" }, "transfer_id": { "type": "string" }, "report_request_id": { "type": [ "string", "null" ] }, "report_created_at": { "type": "integer" }, "received_at": { "type": "integer" }, "image_id": { "type": "string" }, "event": { "type": "string" }, "stage_state": { "type": "string" }, "content_sha256": { "title": "ConsoleDevicesDeviceIdReportsResponseV2ReportContent_Sha256", "type": "object", "properties": { "state": { "type": "string" }, "algo": { "type": "string" } }, "required": [ "state", "algo" ], "additionalProperties": true }, "ios_copy_verify": { "title": "ConsoleDevicesDeviceIdReportsResponseV2ReportIos_Copy_Verify", "type": "object", "properties": { "state": { "type": "string" } }, "required": [ "state" ], "additionalProperties": true }, "sampling": { "title": "ConsoleDevicesDeviceIdReportsResponseV2ReportSampling", "type": "object", "properties": { "sampling_class": { "type": "string" } }, "required": [ "sampling_class" ], "additionalProperties": true }, "peers": { "type": "array", "items": { "type": "string" } }, "peers_total": { "type": "integer" }, "peers_rows_dropped": { "type": "integer" }, "peers_truncated": { "type": "boolean" }, "peers_saturated": { "type": "boolean" } }, "required": [ "v", "schema", "report_id", "transfer_id", "report_request_id", "report_created_at", "received_at", "image_id", "event", "stage_state", "content_sha256", "ios_copy_verify", "sampling", "peers", "peers_total", "peers_rows_dropped", "peers_truncated", "peers_saturated" ], "additionalProperties": true }, { "title": "ConsoleDevicesDeviceIdReportsResponseV1Report", "type": "object", "properties": { "schema": { "type": "string", "const": "v1" }, "event": { "type": "string" }, "image_id": { "type": "string" }, "peers": { "type": "array", "items": { "type": "string" } }, "peers_total": { "type": "integer" }, "peers_rows_dropped": { "type": "integer" }, "received_at": { "type": "integer" }, "_event_id": { "type": "string" } }, "required": [ "schema", "event", "image_id", "peers", "peers_total", "peers_rows_dropped", "received_at", "_event_id" ], "additionalProperties": true } ] } } }, "required": [ "device_id", "observed_at", "pending_request", "reports" ], "additionalProperties": true }, "example": { "device_id": "device-01", "observed_at": 1788470400.5, "pending_request": null, "reports": [ { "v": 2, "schema": "v2", "report_id": "7c1f0b9a2d3e4f5061728394a5b6c7d8", "transfer_id": "3f0a9c1d8e2b4a6f9017c3d5e7b1a2c4", "report_request_id": null, "report_created_at": 1788470300, "received_at": 1788470400, "image_id": "image-01", "event": "staging-complete", "stage_state": "ready", "content_sha256": { "state": "verified", "algo": "sha256" }, "ios_copy_verify": { "state": "ok" }, "sampling": { "sampling_class": "good" }, "peers": [], "peers_total": 0, "peers_rows_dropped": 0, "peers_truncated": false, "peers_saturated": false }, { "schema": "v1", "event": "seeding-only", "image_id": "image-01", "peers": [], "peers_total": 0, "peers_rows_dropped": 0, "received_at": 1788470400, "_event_id": "0123456789abcdef0123456789abcdef" } ] } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Unprocessable content", "x-iris-problem-codes": [ "unprocessable-content" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#unprocessable-content", "title": "Unprocessable content", "status": 422, "code": "unprocessable-content" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/devices/{device_id}/deployment": { "get": { "operationId": "console_get_api_v1_devices_device_id_deployment", "summary": "Read device deployment", "description": "Read device deployment. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" } ], "responses": { "200": { "description": "Read device deployment response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdDeploymentResponse", "type": "object", "properties": { "record": { "oneOf": [ { "title": "ConsoleDevicesDeviceIdDeploymentResponseRecord", "type": "object", "properties": { "record_id": { "type": "string" }, "state": { "type": "string" } }, "required": [ "record_id", "state" ], "additionalProperties": true }, { "type": "null" } ] }, "total": { "type": "integer" } }, "required": [ "record", "total" ], "additionalProperties": true }, "example": { "record": null, "total": 0 } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/devices/{device_id}/certificate": { "get": { "operationId": "console_get_api_v1_devices_device_id_certificate", "summary": "Read device peer certificate status", "description": "Read or withdraw one device's peer TLS certificate identity while retaining its inventory entry. The status 'active' means not revoked; it does not attest that a certificate has been issued or remains valid. Withdrawal requires TLS mode, the reviewed identity SHA256 and revision, and a UUID request_id. The durable request ID is bound to the device, identity and reviewed revision. Retrying the same request is safe; a conflicting review returns 409. A 503 may follow a completed write: GET reconciles the authoritative state. Revoked identities remain denied across restart and inventory removal. The reenroll action approves fresh onboarding for the same inventory entry and returns reenrollment-required; it does not restore old certificate access. Only explicit onboarding, after old catalog credentials are replaced durably, activates the new random certificate identity. Queued or running device jobs must finish first. The response does not prove peer-wide enforcement.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" } ], "responses": { "200": { "description": "Durable certificate identity withdrawal; not proof every peer has applied it", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_id": { "type": "string", "maxLength": 128 }, "identity_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "state": { "enum": [ "active", "revoked", "reenrollment-required" ] }, "revoked_at": { "type": [ "integer", "null" ], "minimum": 0 }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "recovery_request_id": { "type": [ "string", "null" ], "format": "uuid" }, "peer_tls_required": { "type": "boolean" }, "enforcement": { "enum": [ "pending", "not-applicable" ] } }, "required": [ "device_id", "identity_sha256", "revision", "state", "revoked_at", "request_id", "recovery_request_id", "peer_tls_required", "enforcement" ], "additionalProperties": false }, "example": { "device_id": "edge-01", "identity_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "revision": 1, "state": "revoked", "revoked_at": 1788470400, "request_id": "00000000-0000-0000-0000-000000000001", "recovery_request_id": null, "peer_tls_required": true, "enforcement": "pending" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/devices/{device_id}/certificate/revoke": { "post": { "operationId": "console_post_api_v1_devices_device_id_certificate_revoke", "summary": "Revoke a device peer certificate", "description": "Read or withdraw one device's peer TLS certificate identity while retaining its inventory entry. The status 'active' means not revoked; it does not attest that a certificate has been issued or remains valid. Withdrawal requires TLS mode, the reviewed identity SHA256 and revision, and a UUID request_id. The durable request ID is bound to the device, identity and reviewed revision. Retrying the same request is safe; a conflicting review returns 409. A 503 may follow a completed write: GET reconciles the authoritative state. Revoked identities remain denied across restart and inventory removal. The reenroll action approves fresh onboarding for the same inventory entry and returns reenrollment-required; it does not restore old certificate access. Only explicit onboarding, after old catalog credentials are replaced durably, activates the new random certificate identity. Queued or running device jobs must finish first. The response does not prove peer-wide enforcement.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Durable certificate identity withdrawal; not proof every peer has applied it", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_id": { "type": "string", "maxLength": 128 }, "identity_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "state": { "enum": [ "active", "revoked", "reenrollment-required" ] }, "revoked_at": { "type": [ "integer", "null" ], "minimum": 0 }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "recovery_request_id": { "type": [ "string", "null" ], "format": "uuid" }, "peer_tls_required": { "type": "boolean" }, "enforcement": { "enum": [ "pending", "not-applicable" ] }, "applied": { "type": "boolean" } }, "required": [ "device_id", "identity_sha256", "revision", "state", "revoked_at", "request_id", "recovery_request_id", "peer_tls_required", "enforcement", "applied" ], "additionalProperties": false }, "example": { "device_id": "edge-01", "identity_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "revision": 1, "state": "revoked", "revoked_at": 1788470400, "request_id": "00000000-0000-0000-0000-000000000001", "recovery_request_id": null, "peer_tls_required": true, "enforcement": "pending", "applied": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdCertificateRevokeRequest", "type": "object", "properties": { "expected_revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "expected_identity_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "expected_revision", "expected_identity_sha256", "request_id" ], "additionalProperties": false }, "example": { "expected_revision": 0, "expected_identity_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "request_id": "00000000-0000-0000-0000-000000000001" } } } } } }, "/api/v1/devices/{device_id}/certificate/reenroll": { "post": { "operationId": "console_post_api_v1_devices_device_id_certificate_reenroll", "summary": "Approve fresh device certificate onboarding", "description": "Read or withdraw one device's peer TLS certificate identity while retaining its inventory entry. The status 'active' means not revoked; it does not attest that a certificate has been issued or remains valid. Withdrawal requires TLS mode, the reviewed identity SHA256 and revision, and a UUID request_id. The durable request ID is bound to the device, identity and reviewed revision. Retrying the same request is safe; a conflicting review returns 409. A 503 may follow a completed write: GET reconciles the authoritative state. Revoked identities remain denied across restart and inventory removal. The reenroll action approves fresh onboarding for the same inventory entry and returns reenrollment-required; it does not restore old certificate access. Only explicit onboarding, after old catalog credentials are replaced durably, activates the new random certificate identity. Queued or running device jobs must finish first. The response does not prove peer-wide enforcement.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Durable certificate identity withdrawal; not proof every peer has applied it", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_id": { "type": "string", "maxLength": 128 }, "identity_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "state": { "enum": [ "active", "revoked", "reenrollment-required" ] }, "revoked_at": { "type": [ "integer", "null" ], "minimum": 0 }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "recovery_request_id": { "type": [ "string", "null" ], "format": "uuid" }, "peer_tls_required": { "type": "boolean" }, "enforcement": { "enum": [ "pending", "not-applicable" ] }, "applied": { "type": "boolean" } }, "required": [ "device_id", "identity_sha256", "revision", "state", "revoked_at", "request_id", "recovery_request_id", "peer_tls_required", "enforcement", "applied" ], "additionalProperties": false }, "example": { "device_id": "edge-01", "identity_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "revision": 1, "state": "revoked", "revoked_at": 1788470400, "request_id": "00000000-0000-0000-0000-000000000001", "recovery_request_id": null, "peer_tls_required": true, "enforcement": "pending", "applied": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdCertificateReenrollRequest", "type": "object", "properties": { "expected_revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "expected_identity_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "expected_revision", "expected_identity_sha256", "request_id" ], "additionalProperties": false }, "example": { "expected_revision": 1, "expected_identity_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "request_id": "00000000-0000-0000-0000-000000000002" } } } } } }, "/api/v1/devices/{device_id}/assign": { "post": { "operationId": "console_post_api_v1_devices_device_id_assign", "summary": "Assign an image", "description": "Assign an image. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Assign an image response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdAssignResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "assigned_image_ids": { "type": "array", "items": { "type": "string" } }, "removed_image_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "ok", "assigned_image_ids", "removed_image_ids" ], "additionalProperties": true }, "example": { "ok": true, "assigned_image_ids": [ "image-01" ], "removed_image_ids": [] } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Unprocessable content", "x-iris-problem-codes": [ "unprocessable-content" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#unprocessable-content", "title": "Unprocessable content", "status": 422, "code": "unprocessable-content" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdAssignRequest", "type": "object", "properties": { "image_ids": { "type": "array", "items": { "type": "string" } }, "expect_image_ids": { "type": "array", "items": { "type": "string" } }, "image_id": { "type": [ "string", "null" ] } }, "required": [], "additionalProperties": true, "description": "image_ids is the preferred ordered set and wins when both forms are present. image_id is the singular v1 compatibility form. An empty object, empty image_ids, or null image_id unassigns." }, "examples": { "orderedSet": { "value": { "image_ids": [ "image-01" ], "expect_image_ids": [] } }, "singularCompatibility": { "value": { "image_id": "image-01", "expect_image_ids": [] } }, "unassign": { "value": {} } } } } } } }, "/api/v1/devices/{device_id}/credential": { "post": { "operationId": "console_post_api_v1_devices_device_id_credential", "summary": "Assign a credential", "description": "Assign a credential. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Assign a credential response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdCredentialResponse", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdCredentialRequest", "type": "object", "properties": { "credential_profile_id": { "type": "string" } }, "required": [ "credential_profile_id" ], "additionalProperties": true }, "example": { "credential_profile_id": "default" } } } } } }, "/api/v1/devices/{device_id}/platform": { "post": { "operationId": "console_post_api_v1_devices_device_id_platform", "summary": "Set device platform", "description": "Set device platform. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Set device platform response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdPlatformResponse", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdPlatformRequest", "type": "object", "properties": { "platform": { "type": "string" } }, "required": [ "platform" ], "additionalProperties": true }, "example": { "platform": "iox" } } } } } }, "/api/v1/devices/{device_id}/forget-host-key": { "post": { "operationId": "console_post_api_v1_devices_device_id_forget_host_key", "summary": "Forget SSH host key", "description": "Forget SSH host key. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Forget SSH host key response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdForgetHostKeyResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "peer": { "type": "string" } }, "required": [ "ok", "peer" ], "additionalProperties": true }, "example": { "ok": true, "peer": "192.0.2.10" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdForgetHostKeyRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/api/v1/devices/{device_id}/request-report": { "post": { "operationId": "console_post_api_v1_devices_device_id_request_report", "summary": "Request a device report", "description": "Request a device report. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Request a device report response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdRequestReportResponse", "type": "object", "properties": { "ok": { "const": true }, "device_id": { "type": "string" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "requested_at": { "type": "number" }, "expires_at": { "type": "number" } }, "required": [ "ok", "device_id", "request_id", "requested_at", "expires_at" ], "additionalProperties": true }, "example": { "ok": true, "device_id": "device-01", "request_id": "0123456789abcdef0123456789abcdef", "requested_at": 1788473400.5, "expires_at": 1788474000.5 } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Unprocessable content", "x-iris-problem-codes": [ "unprocessable-content" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#unprocessable-content", "title": "Unprocessable content", "status": 422, "code": "unprocessable-content" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdRequestReportRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/api/v1/devices/{device_id}/peer-telemetry": { "post": { "operationId": "console_post_api_v1_devices_device_id_peer_telemetry", "summary": "Set peer telemetry interval", "description": "Set peer telemetry interval. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "dry_run", "in": "query", "required": false, "description": "1 previews the locked candidate without persistence; 0 commits after required confirmation.", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "example": 1 }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong policy ETag. Missing: 428; stale: 412; race under the policy lock: 409. Confirmation is candidate-bound at threshold zero, including every changed QoS document.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Set peer telemetry interval response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdPeerTelemetryResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "candidate_revision": { "type": "integer" }, "dry_run": { "type": "boolean" }, "member_delta": { "type": "integer" }, "origin_access_lost": { "type": "integer" }, "empty_permitted_sets": { "type": "integer" }, "role_pairs_stopped": { "type": "integer" }, "qos_changed": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ] }, "device_id": { "type": "string" }, "requested_interval_s": { "type": "integer" } }, "required": [ "ok", "revision", "candidate_revision", "dry_run", "member_delta", "origin_access_lost", "empty_permitted_sets", "role_pairs_stopped", "qos_changed", "requires_confirmation", "confirm_token", "device_id", "requested_interval_s" ], "additionalProperties": true }, "examples": { "confirmationRequired": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 1, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": true, "confirm_token": "candidate-bound-sha256", "device_id": "edge-01", "requested_interval_s": 10 } }, "noConfirmation": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": false, "confirm_token": null, "device_id": "edge-01", "requested_interval_s": 10 } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "400": { "description": "Invalid content length or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Device not found or Route not found", "x-iris-problem-codes": [ "device_not_found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "device_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#device_not_found", "title": "Device not found", "status": 404, "code": "device_not_found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "409": { "description": "Operation backlog full or Revision conflict", "x-iris-problem-codes": [ "operation_backlog_full", "revision_conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "operation_backlog_full": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#operation_backlog_full", "title": "Operation backlog full", "status": 409, "code": "operation_backlog_full" } }, "revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#revision_conflict", "title": "Revision conflict", "status": 409, "code": "revision_conflict" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid policy or Invalid policy request or Peer telemetry unsupported", "x-iris-problem-codes": [ "invalid_policy", "invalid_policy_request", "peer_telemetry_unsupported" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_policy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy", "title": "Invalid policy", "status": 422, "code": "invalid_policy" } }, "invalid_policy_request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } }, "peer_telemetry_unsupported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#peer_telemetry_unsupported", "title": "Peer telemetry unsupported", "status": 422, "code": "peer_telemetry_unsupported" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Confirmation required or Precondition required", "x-iris-problem-codes": [ "confirmation_required", "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "confirmation_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#confirmation_required", "title": "Confirmation required", "status": 428, "code": "confirmation_required" } }, "precondition_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management api unavailable or Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdPeerTelemetryRequest", "type": "object", "properties": { "interval_s": { "type": "integer", "enum": [ 10, 60 ] }, "confirm_token": { "type": [ "string", "null" ], "writeOnly": true } }, "required": [ "interval_s" ], "additionalProperties": false }, "example": { "interval_s": 10, "confirm_token": "candidate-bound-sha256" } } } } } }, "/api/v1/devices/{device_id}/adopt": { "post": { "operationId": "console_post_api_v1_devices_device_id_adopt", "summary": "Adopt a deployment", "description": "Adopt a deployment. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Adopt a deployment response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdAdoptResponse", "type": "object", "properties": { "record_id": { "type": "string" } }, "required": [ "record_id" ], "additionalProperties": true }, "example": { "record_id": "record-01" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdAdoptRequest", "type": "object", "properties": { "acknowledge_adopt": { "type": "boolean" } }, "required": [ "acknowledge_adopt" ], "additionalProperties": true }, "example": { "acknowledge_adopt": true } } } } } }, "/api/v1/devices/{device_id}/onboard": { "post": { "operationId": "console_post_api_v1_devices_device_id_onboard", "summary": "Start device onboarding", "description": "Start device onboarding. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Start device onboarding response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdOnboardResponse", "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ], "additionalProperties": true }, "example": { "job_id": "job-01" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdOnboardRequest", "type": "object", "properties": { "telemetry": { "type": "boolean" }, "telemetry_stream": { "type": "boolean" }, "log": { "type": "boolean", "default": false, "description": "Enable detailed IOx command output in the job log. Onboarding also enables download logs on IOx and IOS-XR. Guest Shell logging is configured separately." } }, "required": [], "additionalProperties": true }, "example": { "telemetry": true, "telemetry_stream": false, "log": false } } } } } }, "/api/v1/devices/{device_id}/undeploy": { "post": { "operationId": "console_post_api_v1_devices_device_id_undeploy", "summary": "Start device removal", "description": "Start device removal. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Start device removal response", "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdUndeployResponse", "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ], "additionalProperties": true }, "example": { "job_id": "job-01" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleDevicesDeviceIdUndeployRequest", "type": "object", "properties": { "force": { "type": "boolean" }, "log": { "type": "boolean", "default": false, "description": "Enable detailed IOx command output in the job log. Onboarding also enables download logs on IOx and IOS-XR. Guest Shell logging is configured separately." } }, "required": [], "additionalProperties": true }, "example": { "force": false, "log": false } } } } } }, "/api/v1/install-options": { "get": { "operationId": "console_get_api_v1_install_options", "summary": "List install options", "description": "List install options. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Without management_type, this retains the model-only response; null means no model-based restriction. With management_type, options is always an array of choices accepted for that model and management pair; an incompatible pair or invalid type returns an empty array. Management type alone controls network-field visibility in the Console. A saved free-text model does not confirm hardware support.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "model", "in": "query", "required": false, "description": "Device model used to derive supported install methods", "schema": { "type": "string" }, "example": "IE-3400" }, { "name": "management_type", "in": "query", "required": false, "description": "Restrict to the model and management pair; blank or unknown types return no options", "schema": { "type": "string" }, "example": "inband" } ], "responses": { "200": { "description": "List install options response", "content": { "application/json": { "schema": { "title": "ConsoleInstallOptionsResponse", "type": "object", "properties": { "options": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "options" ], "additionalProperties": true }, "example": { "options": [ "guestshell", "iox" ] } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/credentials": { "get": { "operationId": "console_get_api_v1_credentials", "summary": "List credential profiles", "description": "List credential profiles. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. This bounded v1 collection has no pagination parameter; adding one without a stable compatibility shape is deferred to the next major version.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "List credential profiles response", "content": { "application/json": { "schema": { "title": "ConsoleCredentialsResponse", "type": "object", "properties": { "profiles": { "type": "array", "items": { "title": "ConsoleCredentialsResponseProfilesItem", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "device_user": { "type": "string" } }, "required": [ "id", "name", "device_user" ], "additionalProperties": true } } }, "required": [ "profiles" ], "additionalProperties": true }, "example": { "profiles": [ { "id": "default", "name": "Default devices", "device_user": "operator" } ] } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "console_post_api_v1_credentials", "summary": "Create a credential profile", "description": "Create a credential profile. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Create a credential profile response", "content": { "application/json": { "schema": { "title": "ConsoleCredentialsResponse", "type": "object", "properties": { "profile": { "title": "ConsoleCredentialsResponseProfile", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "device_user": { "type": "string" } }, "required": [ "id", "name", "device_user" ], "additionalProperties": true } }, "required": [ "profile" ], "additionalProperties": true }, "example": { "profile": { "id": "default", "name": "Default devices", "device_user": "operator" } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleCredentialsRequest", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "device_user": { "type": "string", "description": "Must not contain U+0000 (NUL)." }, "device_pass": { "type": "string", "format": "password", "writeOnly": true, "description": "Must not contain U+0000 (NUL)." }, "enable_secret": { "type": "string", "format": "password", "writeOnly": true, "description": "Must not contain U+0000 (NUL)." } }, "required": [ "id", "name", "device_user", "device_pass" ], "additionalProperties": true }, "example": { "id": "default", "name": "Default devices", "device_user": "operator", "device_pass": "device-password", "enable_secret": "enable-password" } } } } } }, "/api/v1/credentials/{credential_id}": { "delete": { "operationId": "console_delete_api_v1_credentials_credential_id", "summary": "Delete a credential profile", "description": "Delete a credential profile. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "credential_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Delete a credential profile response", "content": { "application/json": { "schema": { "title": "ConsoleCredentialsCredentialIdResponse", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": true }, "example": { "deleted": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/onboard/jobs": { "get": { "operationId": "console_get_api_v1_onboard_jobs", "summary": "List onboarding jobs", "description": "List onboarding jobs. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. This bounded v1 collection has no pagination parameter; adding one without a stable compatibility shape is deferred to the next major version.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "List onboarding jobs response", "content": { "application/json": { "schema": { "title": "ConsoleOnboardJobsResponse", "type": "object", "properties": { "jobs": { "type": "array", "items": { "title": "ConsoleOnboardJobsResponseJobsItem", "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "state" ], "additionalProperties": true } }, "max_concurrent": { "type": "integer" }, "now": { "type": "integer" } }, "required": [ "jobs", "max_concurrent", "now" ], "additionalProperties": true }, "example": { "jobs": [ { "id": "job-01", "state": "running" } ], "max_concurrent": 4, "now": 1788470400 } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/onboard/jobs/{job_id}": { "get": { "operationId": "console_get_api_v1_onboard_jobs_job_id", "summary": "Read onboarding job", "description": "Read onboarding job. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" } ], "responses": { "200": { "description": "Read onboarding job response", "content": { "application/json": { "schema": { "title": "ConsoleOnboardJobsJobIdResponse", "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "device_id": { "type": "string" } }, "required": [ "id", "state", "device_id" ], "additionalProperties": true }, "example": { "id": "job-01", "state": "running", "device_id": "edge-01" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/onboard/jobs/{job_id}/stream": { "get": { "operationId": "console_get_api_v1_onboard_jobs_job_id_stream", "summary": "Stream onboarding job output", "description": "Stream onboarding job output. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" } ], "responses": { "200": { "description": "Job log lines as unnamed text data events, with keepalive comments. An end event carries done, error, cancelled, idle, or unknown. Each connection replays the retained lines from the start; Last-Event-ID is not supported.", "content": { "text/event-stream": { "itemSchema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string" }, "event": { "enum": [ "message", "end" ] } }, "if": { "required": [ "event" ], "properties": { "event": { "const": "end" } } }, "then": { "properties": { "data": { "enum": [ "done", "error", "cancelled", "idle", "unknown" ] } } } }, "examples": { "completed": { "summary": "A log line followed by completion", "serializedValue": "data: onboard complete: 192.0.2.10\n\nevent: end\ndata: done\n\n" } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/onboard/jobs/{job_id}/abort": { "post": { "operationId": "console_post_api_v1_onboard_jobs_job_id_abort", "summary": "Abort onboarding job", "description": "Abort onboarding job. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. onboarding job control: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Abort onboarding job response", "content": { "application/json": { "schema": { "title": "ConsoleOnboardJobsJobIdAbortResponse", "type": "object", "properties": { "aborted": { "type": "boolean" } }, "required": [ "aborted" ], "additionalProperties": true }, "example": { "aborted": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "onboarding job control: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleOnboardJobsJobIdAbortRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/api/v1/onboard/cancel-queued": { "post": { "operationId": "console_post_api_v1_onboard_cancel_queued", "summary": "Cancel queued onboarding jobs", "description": "Cancel queued onboarding jobs. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. onboarding job control: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Cancel queued onboarding jobs response", "content": { "application/json": { "schema": { "title": "ConsoleOnboardCancelQueuedResponse", "type": "object", "properties": { "cancelled": { "type": "integer" } }, "required": [ "cancelled" ], "additionalProperties": true }, "example": { "cancelled": 1 } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "onboarding job control: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleOnboardCancelQueuedRequest", "type": "object", "properties": { "job_ids": { "type": "array", "items": { "type": "string" } } }, "required": [], "additionalProperties": true }, "example": { "job_ids": [ "job-01" ] } } } } } }, "/api/v1/deploy-logs": { "get": { "operationId": "console_get_api_v1_deploy_logs", "summary": "List deployment logs", "description": "List deployment logs. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "device_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "edge-01" }, { "name": "after_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788384000 }, { "name": "before_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788470400 } ], "responses": { "200": { "description": "List deployment logs response", "content": { "application/json": { "schema": { "title": "ConsoleDeployLogsResponse", "type": "object", "properties": { "logs": { "type": "array", "items": { "title": "ConsoleDeployLogsResponseLogsItem", "type": "object", "properties": { "file": { "type": "string" }, "device_id": { "type": "string" }, "action": { "type": "string" }, "state": { "type": "string" }, "rc": { "type": "integer" }, "finished_at": { "type": "integer" }, "size": { "type": "integer" } }, "required": [ "file", "device_id", "action", "state", "rc", "finished_at", "size" ], "additionalProperties": true } } }, "required": [ "logs" ], "additionalProperties": true }, "example": { "logs": [ { "file": "1788470400-edge-01-onboard-job-01.log", "device_id": "edge-01", "action": "onboard", "state": "done", "rc": 0, "finished_at": 1788470400, "size": 1024 } ] } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/deploy-logs/histogram": { "get": { "operationId": "console_get_api_v1_deploy_logs_histogram", "summary": "Read deployment log histogram", "description": "Read deployment log histogram. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "device_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "edge-01" }, { "name": "buckets", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "example": 30 }, { "name": "window", "in": "query", "required": false, "schema": { "type": "number", "minimum": 60 }, "example": 604800 }, { "name": "since_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788384000 }, { "name": "until_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788470400 } ], "responses": { "200": { "description": "Read deployment log histogram response", "content": { "application/json": { "schema": { "title": "ConsoleDeployLogsHistogramResponse", "type": "object", "properties": { "buckets": { "type": "array", "items": { "title": "ConsoleDeployLogsHistogramResponseBucketsItem", "type": "object", "properties": { "start": { "type": "integer" }, "count": { "type": "integer" } }, "required": [ "start", "count" ], "additionalProperties": true } }, "now": { "type": "integer" } }, "required": [ "buckets", "now" ], "additionalProperties": true }, "example": { "buckets": [ { "start": 1788470400, "count": 1 } ], "now": 1788474000 } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/deploy-logs/{filename}": { "get": { "operationId": "console_get_api_v1_deploy_logs_filename", "summary": "Read deployment log", "description": "Read deployment log. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "filename", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" } ], "responses": { "200": { "description": "Deployment log text", "content": { "text/plain": { "schema": { "type": "string" }, "example": "onboard started\n" } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/overview": { "get": { "operationId": "console_get_api_v1_overview", "summary": "Read fleet overview", "description": "Read fleet overview. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read fleet overview response", "content": { "application/json": { "schema": { "title": "ConsoleOverviewResponse", "type": "object", "properties": { "images": { "type": "integer" }, "devices": { "type": "integer" }, "assigned": { "type": "integer" }, "staged": { "type": "integer" }, "staging_now": { "type": "integer" }, "awaiting_heartbeat": { "type": "integer" }, "rollout": { "type": "array", "items": { "title": "ConsoleOverviewResponseRolloutItem", "type": "object", "properties": { "image_id": { "type": "string" }, "filename": { "type": "string" }, "assigned": { "type": "integer" }, "staged": { "type": "integer" } }, "required": [ "image_id", "filename", "assigned", "staged" ], "additionalProperties": true } }, "swarm_map_url": { "type": "string" } }, "required": [ "images", "devices", "assigned", "staged", "staging_now", "awaiting_heartbeat", "rollout", "swarm_map_url" ], "additionalProperties": true }, "example": { "images": 1, "devices": 1, "assigned": 1, "staged": 1, "staging_now": 0, "awaiting_heartbeat": 0, "rollout": [ { "image_id": "image-01", "filename": "image.bin", "assigned": 1, "staged": 1 } ], "swarm_map_url": "/swarmmap" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Device status temporarily busy or Service unavailable or Management API unavailable", "x-iris-problem-codes": [ "projection-busy", "service-unavailable", "management-api-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "projection-busy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#projection-busy", "title": "Device status temporarily busy", "status": 503, "code": "projection-busy" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } }, "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/deployment": { "get": { "operationId": "console_get_api_v1_deployment", "summary": "Read deployment layout and runtime inventory", "description": "Read deployment layout and runtime inventory. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read-only deployment inventory or explicitly limited runtime observations", "content": { "application/json": { "schema": { "type": "object", "properties": { "layout": { "enum": [ "docker", "docker-split", "kubernetes", "single-container", "unknown" ] }, "source": { "enum": [ "managed-worker", "runtime" ] }, "observed_at": { "type": "integer", "minimum": 0 }, "instance": { "type": [ "string", "null" ], "maxLength": 256 }, "namespace": { "type": [ "string", "null" ], "maxLength": 256 }, "note": { "type": [ "string", "null" ], "maxLength": 256 }, "components": { "type": "array", "maxItems": 64, "items": { "type": "object", "properties": { "role": { "enum": [ "server", "console" ] }, "kind": { "enum": [ "container", "pod", "process" ] }, "name": { "type": [ "string", "null" ], "maxLength": 256 }, "host": { "type": [ "string", "null" ], "maxLength": 256 }, "address": { "type": [ "string", "null" ], "maxLength": 256 }, "image": { "type": [ "string", "null" ], "maxLength": 256 }, "state": { "type": [ "string", "null" ], "maxLength": 256 }, "os": { "type": [ "string", "null" ], "maxLength": 256 }, "architecture": { "type": [ "string", "null" ], "maxLength": 256 }, "kernel": { "type": [ "string", "null" ], "maxLength": 256 } }, "required": [ "role", "kind", "name", "host", "address", "image", "state", "os", "architecture", "kernel" ], "additionalProperties": false } } }, "required": [ "layout", "source", "observed_at", "instance", "namespace", "note", "components" ], "additionalProperties": false }, "example": { "layout": "docker", "source": "managed-worker", "observed_at": 1788470400, "instance": "iris", "namespace": null, "note": null, "components": [ { "role": "server", "kind": "container", "name": "iris-server", "host": "staging-host", "address": null, "image": "iris:latest", "state": "running / healthy", "os": "Debian GNU/Linux", "architecture": "x86_64", "kernel": "6.8.0" } ] } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/swarm": { "get": { "operationId": "console_get_api_v1_swarm", "summary": "Read swarm state", "description": "Read swarm state. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Image rows include image_id when the torrent hash maps to one catalog image. Observations and reports carry image_id when known; match it before attributing measurements. Tracker seeder role does not establish device staging completion, and ambiguous peer rates remain unavailable.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Peer page size; omit for the complete compatibility response", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "example": 100 }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "example": 0 } ], "responses": { "200": { "description": "Whole swarm, an opt-in peer page, or an availability fallback", "content": { "application/json": { "schema": { "oneOf": [ { "title": "ConsoleSwarmWholeResponse", "type": "object", "properties": { "now": { "type": "number" }, "server": { "title": "ConsoleSwarmWholeResponseServer", "type": "object", "properties": { "host": { "type": "string" }, "server_observation": { "title": "ConsoleSwarmWholeResponseServerServer_Observation", "type": "object", "properties": { "observed_at": { "type": [ "number", "null" ] }, "rpc_up": { "type": "boolean" }, "unavailable": { "type": "boolean" }, "aria_session_id": { "type": [ "string", "null" ] }, "peer_tls": { "type": "object", "additionalProperties": false, "required": [ "runtime_mode", "runtime_source" ], "properties": { "runtime_mode": { "enum": [ "disabled", "required", "unknown" ] }, "runtime_source": { "enum": [ "aria2_rpc", "unknown" ] }, "revocations": { "type": "object", "properties": { "supported": { "const": true }, "mode": { "enum": [ "required", "disabled" ] }, "state": { "enum": [ "valid", "unavailable", "expired" ] }, "authority": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "issued_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "expires_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "own_revoked": { "type": "boolean" }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "supported", "mode", "state", "authority", "revision", "issued_at", "expires_at", "own_revoked", "observed_at" ], "additionalProperties": false }, "reported_at": { "type": [ "number", "null" ] } }, "description": "Last reported torrent TLS daemon policy, not negotiated connection evidence. Missing means unknown." } }, "required": [ "observed_at", "rpc_up", "unavailable", "aria_session_id" ], "additionalProperties": true } }, "required": [ "host", "server_observation" ], "additionalProperties": true }, "images": { "type": "array", "items": { "title": "ConsoleSwarmWholeResponseImagesItem", "type": "object", "properties": { "image": { "type": "string" }, "info_hash": { "type": "string" }, "total_bytes": { "type": [ "integer", "null" ] }, "seeders": { "type": "integer" }, "leechers": { "type": "integer" }, "peers": { "type": "array", "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "ip", "port", "tracker", "device_id" ], "properties": { "ip": { "type": "string" }, "port": { "type": "integer" }, "tracker": { "type": "object", "additionalProperties": false, "required": [ "principal_type", "role", "left", "last_seen", "progress", "principal_id" ], "properties": { "principal_type": { "const": "device" }, "role": { "enum": [ "seeder", "leecher" ] }, "left": { "type": [ "integer", "null" ] }, "last_seen": { "type": [ "number", "null" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "principal_id": { "type": "string" } } }, "device_observation": { "type": "object" }, "server_observation": { "type": "object" }, "latest_report": { "type": "object" }, "peer_policy": { "type": "object" }, "peer_enforcement": { "type": "object" }, "device_id": { "type": "string" }, "peer_tls": { "type": "object", "additionalProperties": false, "required": [ "configured_mode", "runtime_mode", "runtime_source" ], "properties": { "configured_mode": { "enum": [ "disabled", "required" ] }, "runtime_mode": { "enum": [ "disabled", "required", "unknown" ] }, "runtime_source": { "enum": [ "aria2_rpc", "unknown" ] }, "revocations": { "type": "object", "properties": { "supported": { "const": true }, "mode": { "enum": [ "required", "disabled" ] }, "state": { "enum": [ "valid", "unavailable", "expired" ] }, "authority": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "issued_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "expires_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "own_revoked": { "type": "boolean" }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "supported", "mode", "state", "authority", "revision", "issued_at", "expires_at", "own_revoked", "observed_at" ], "additionalProperties": false }, "reported_at": { "type": [ "number", "null" ] } }, "description": "Last reported torrent TLS daemon policy, not negotiated connection evidence. Missing means unknown." }, "peer_telemetry": { "type": "object", "additionalProperties": false, "properties": { "supported": { "type": "boolean" }, "requested_interval_s": { "enum": [ 10, 60, null ] }, "effective_interval_s": { "type": [ "integer", "null" ] } } }, "model": { "type": "string" }, "current_image_id": { "type": "string" }, "stage_state": { "type": "string" }, "staged_image_ids": { "type": "array", "items": { "type": "string" } }, "errored_image_ids": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": [ "ip", "port", "tracker" ], "properties": { "ip": { "type": "string" }, "port": { "type": "integer" }, "tracker": { "type": "object", "additionalProperties": false, "required": [ "principal_type", "role", "left", "last_seen", "progress", "principal_id" ], "properties": { "principal_type": { "const": "service" }, "role": { "enum": [ "seeder", "leecher" ] }, "left": { "type": [ "integer", "null" ] }, "last_seen": { "type": [ "number", "null" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "principal_id": { "type": "string" } } }, "device_observation": { "type": "object" }, "server_observation": { "type": "object" }, "latest_report": { "type": "object" }, "peer_policy": { "type": "object" }, "peer_enforcement": { "type": "object" } } }, { "type": "object", "additionalProperties": false, "required": [ "ip", "port", "tracker" ], "properties": { "ip": { "type": "string" }, "port": { "type": "integer" }, "tracker": { "type": "object", "additionalProperties": false, "required": [ "principal_type", "role", "left", "last_seen", "progress" ], "properties": { "principal_type": { "const": "legacy" }, "role": { "enum": [ "seeder", "leecher" ] }, "left": { "type": [ "integer", "null" ] }, "last_seen": { "type": [ "number", "null" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "participant_class": { "type": "string" } } }, "device_id": { "type": "null" }, "warning": { "const": "legacy_unattributed" }, "quarantine_available": { "const": false } } } ] } }, "peer_edges": { "type": "array", "maxItems": 1024, "items": { "type": "object", "properties": { "source_device_id": { "type": "string" }, "target_device_id": { "type": "string" }, "reporter_device_id": { "type": "string" }, "bytes_per_second": { "type": "integer", "minimum": 1 }, "connection_count": { "type": "integer", "minimum": 1, "maximum": 32 }, "rate_field": { "enum": [ "send_bps", "receive_bps" ] }, "identity_basis": { "enum": [ "tracker_endpoint", "unique_tracker_address" ] }, "received_at": { "type": "number" }, "observed_at": { "type": [ "number", "null" ] }, "age_s": { "type": "integer", "minimum": 0 }, "valid_for_s": { "type": "integer", "minimum": 1, "maximum": 120 } }, "required": [ "source_device_id", "target_device_id", "reporter_device_id", "bytes_per_second", "connection_count", "rate_field", "identity_basis", "received_at", "observed_at", "age_s", "valid_for_s" ], "additionalProperties": false } }, "peer_edges_truncated": { "type": "boolean" }, "unattributed_peer_connections": { "type": "integer", "minimum": 0 } }, "required": [ "image", "info_hash", "total_bytes", "seeders", "leechers", "peers" ], "additionalProperties": true } } }, "required": [ "now", "server", "images" ], "additionalProperties": false }, { "title": "ConsoleSwarmPageResponse", "type": "object", "properties": { "now": { "type": "number" }, "server": { "title": "ConsoleSwarmPageResponseServer", "type": "object", "properties": { "host": { "type": "string" }, "server_observation": { "title": "ConsoleSwarmPageResponseServerServer_Observation", "type": "object", "properties": { "observed_at": { "type": [ "number", "null" ] }, "rpc_up": { "type": "boolean" }, "unavailable": { "type": "boolean" }, "aria_session_id": { "type": [ "string", "null" ] }, "peer_tls": { "type": "object", "additionalProperties": false, "required": [ "runtime_mode", "runtime_source" ], "properties": { "runtime_mode": { "enum": [ "disabled", "required", "unknown" ] }, "runtime_source": { "enum": [ "aria2_rpc", "unknown" ] }, "revocations": { "type": "object", "properties": { "supported": { "const": true }, "mode": { "enum": [ "required", "disabled" ] }, "state": { "enum": [ "valid", "unavailable", "expired" ] }, "authority": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "issued_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "expires_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "own_revoked": { "type": "boolean" }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "supported", "mode", "state", "authority", "revision", "issued_at", "expires_at", "own_revoked", "observed_at" ], "additionalProperties": false }, "reported_at": { "type": [ "number", "null" ] } }, "description": "Last reported torrent TLS daemon policy, not negotiated connection evidence. Missing means unknown." } }, "required": [ "observed_at", "rpc_up", "unavailable", "aria_session_id" ], "additionalProperties": true } }, "required": [ "host", "server_observation" ], "additionalProperties": true }, "images": { "type": "array", "items": { "title": "ConsoleSwarmPageResponseImagesItem", "type": "object", "properties": { "image": { "type": "string" }, "info_hash": { "type": "string" }, "total_bytes": { "type": [ "integer", "null" ] }, "seeders": { "type": "integer" }, "leechers": { "type": "integer" }, "peers": { "type": "array", "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "ip", "port", "tracker", "device_id" ], "properties": { "ip": { "type": "string" }, "port": { "type": "integer" }, "tracker": { "type": "object", "additionalProperties": false, "required": [ "principal_type", "role", "left", "last_seen", "progress", "principal_id" ], "properties": { "principal_type": { "const": "device" }, "role": { "enum": [ "seeder", "leecher" ] }, "left": { "type": [ "integer", "null" ] }, "last_seen": { "type": [ "number", "null" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "principal_id": { "type": "string" } } }, "device_observation": { "type": "object" }, "server_observation": { "type": "object" }, "latest_report": { "type": "object" }, "peer_policy": { "type": "object" }, "peer_enforcement": { "type": "object" }, "device_id": { "type": "string" }, "peer_tls": { "type": "object", "additionalProperties": false, "required": [ "configured_mode", "runtime_mode", "runtime_source" ], "properties": { "configured_mode": { "enum": [ "disabled", "required" ] }, "runtime_mode": { "enum": [ "disabled", "required", "unknown" ] }, "runtime_source": { "enum": [ "aria2_rpc", "unknown" ] }, "revocations": { "type": "object", "properties": { "supported": { "const": true }, "mode": { "enum": [ "required", "disabled" ] }, "state": { "enum": [ "valid", "unavailable", "expired" ] }, "authority": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "issued_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "expires_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "own_revoked": { "type": "boolean" }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "supported", "mode", "state", "authority", "revision", "issued_at", "expires_at", "own_revoked", "observed_at" ], "additionalProperties": false }, "reported_at": { "type": [ "number", "null" ] } }, "description": "Last reported torrent TLS daemon policy, not negotiated connection evidence. Missing means unknown." }, "peer_telemetry": { "type": "object", "additionalProperties": false, "properties": { "supported": { "type": "boolean" }, "requested_interval_s": { "enum": [ 10, 60, null ] }, "effective_interval_s": { "type": [ "integer", "null" ] } } }, "model": { "type": "string" }, "current_image_id": { "type": "string" }, "stage_state": { "type": "string" }, "staged_image_ids": { "type": "array", "items": { "type": "string" } }, "errored_image_ids": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": [ "ip", "port", "tracker" ], "properties": { "ip": { "type": "string" }, "port": { "type": "integer" }, "tracker": { "type": "object", "additionalProperties": false, "required": [ "principal_type", "role", "left", "last_seen", "progress", "principal_id" ], "properties": { "principal_type": { "const": "service" }, "role": { "enum": [ "seeder", "leecher" ] }, "left": { "type": [ "integer", "null" ] }, "last_seen": { "type": [ "number", "null" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "principal_id": { "type": "string" } } }, "device_observation": { "type": "object" }, "server_observation": { "type": "object" }, "latest_report": { "type": "object" }, "peer_policy": { "type": "object" }, "peer_enforcement": { "type": "object" } } }, { "type": "object", "additionalProperties": false, "required": [ "ip", "port", "tracker" ], "properties": { "ip": { "type": "string" }, "port": { "type": "integer" }, "tracker": { "type": "object", "additionalProperties": false, "required": [ "principal_type", "role", "left", "last_seen", "progress" ], "properties": { "principal_type": { "const": "legacy" }, "role": { "enum": [ "seeder", "leecher" ] }, "left": { "type": [ "integer", "null" ] }, "last_seen": { "type": [ "number", "null" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "participant_class": { "type": "string" } } }, "device_id": { "type": "null" }, "warning": { "const": "legacy_unattributed" }, "quarantine_available": { "const": false } } } ] } }, "peer_edges": { "type": "array", "maxItems": 1024, "items": { "type": "object", "properties": { "source_device_id": { "type": "string" }, "target_device_id": { "type": "string" }, "reporter_device_id": { "type": "string" }, "bytes_per_second": { "type": "integer", "minimum": 1 }, "connection_count": { "type": "integer", "minimum": 1, "maximum": 32 }, "rate_field": { "enum": [ "send_bps", "receive_bps" ] }, "identity_basis": { "enum": [ "tracker_endpoint", "unique_tracker_address" ] }, "received_at": { "type": "number" }, "observed_at": { "type": [ "number", "null" ] }, "age_s": { "type": "integer", "minimum": 0 }, "valid_for_s": { "type": "integer", "minimum": 1, "maximum": 120 } }, "required": [ "source_device_id", "target_device_id", "reporter_device_id", "bytes_per_second", "connection_count", "rate_field", "identity_basis", "received_at", "observed_at", "age_s", "valid_for_s" ], "additionalProperties": false } }, "peer_edges_truncated": { "type": "boolean" }, "unattributed_peer_connections": { "type": "integer", "minimum": 0 } }, "required": [ "image", "info_hash", "total_bytes", "seeders", "leechers", "peers" ], "additionalProperties": true } }, "peers_total": { "type": "integer" }, "peers_offset": { "type": "integer" }, "peers_limit": { "type": [ "integer", "null" ] } }, "required": [ "now", "server", "images", "peers_total", "peers_offset", "peers_limit" ], "additionalProperties": false }, { "title": "ConsoleSwarmUnavailableResponse", "type": "object", "properties": { "peers": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } }, "required": [ "peers", "error" ], "additionalProperties": false } ] }, "examples": { "whole": { "value": { "now": 1788470400.0, "server": { "host": "192.0.2.1", "server_observation": { "observed_at": 1788470400, "rpc_up": true, "unavailable": false, "aria_session_id": "session-01" } }, "images": [ { "image": "image.bin", "info_hash": "0000000000000000000000000000000000000000", "total_bytes": 1048576, "seeders": 1, "leechers": 0, "peers": [ { "device_id": "edge-01", "ip": "192.0.2.10", "port": 6881, "tracker": { "principal_type": "device", "principal_id": "edge-01", "role": "seeder", "left": 0, "last_seen": 1788470400.0, "progress": 1.0 } } ] } ] } }, "page": { "value": { "now": 1788470400.0, "server": { "host": "192.0.2.1", "server_observation": { "observed_at": 1788470400, "rpc_up": true, "unavailable": false, "aria_session_id": "session-01" } }, "images": [ { "image": "image.bin", "info_hash": "0000000000000000000000000000000000000000", "total_bytes": 1048576, "seeders": 1, "leechers": 0, "peers": [ { "device_id": "edge-01", "ip": "192.0.2.10", "port": 6881, "tracker": { "principal_type": "device", "principal_id": "edge-01", "role": "seeder", "left": 0, "last_seen": 1788470400.0, "progress": 1.0 } } ] } ], "peers_total": 1, "peers_offset": 0, "peers_limit": 100 } }, "unavailable": { "value": { "peers": [], "error": "swarm data unavailable" } } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/telemetry/health": { "get": { "operationId": "console_get_api_v1_telemetry_health", "summary": "Read telemetry health", "description": "Read telemetry health. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Detailed exporter status or a non-secret availability fallback", "content": { "application/json": { "schema": { "oneOf": [ { "title": "ConsoleTelemetryHealthResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "otlp_export": { "title": "ConsoleTelemetryHealthResponseOtlp_Export", "type": "object", "properties": { "state": { "type": "string" }, "signals": { "title": "ConsoleTelemetryHealthResponseOtlp_ExportSignals", "type": "object", "properties": {}, "required": [], "additionalProperties": true } }, "required": [ "state", "signals" ], "additionalProperties": true } }, "required": [ "ok", "otlp_export" ], "additionalProperties": false }, { "title": "ConsoleTelemetryHealthUnavailableResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "ok", "error" ], "additionalProperties": false } ] }, "examples": { "healthy": { "value": { "ok": true, "otlp_export": { "state": "healthy", "signals": {} } } }, "unavailable": { "value": { "ok": false, "error": "unavailable" } } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/telemetry/stream": { "post": { "operationId": "console_post_api_v1_telemetry_stream", "summary": "Proxy telemetry stream", "description": "Proxy telemetry stream. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. telemetry stream control: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Proxy telemetry stream response", "content": { "application/json": { "schema": { "title": "ConsoleTelemetryStreamResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "stream_every": { "type": "integer" }, "stream_pause": { "type": "boolean" } }, "required": [ "ok", "stream_every", "stream_pause" ], "additionalProperties": true }, "example": { "ok": true, "stream_every": 4, "stream_pause": false } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "telemetry stream control: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleTelemetryStreamRequest", "type": "object", "properties": { "every": { "type": "integer" }, "pause": { "type": "boolean" } }, "required": [], "additionalProperties": true }, "example": { "every": 4, "pause": false } } } } } }, "/api/v1/settings": { "get": { "operationId": "console_get_api_v1_settings", "summary": "Read settings", "description": "Read settings. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. host_ip identifies the device-facing server; console_url is the configured browser origin and may use another host. gui_cert describes the certificate loaded by this Console, including an independently mounted deployment default.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read settings response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsResponse", "type": "object", "properties": { "admin_username": { "type": "string" }, "trust": { "type": "array", "items": { "type": "string" } }, "host_ip": { "type": "string" }, "console_url": { "type": "string" }, "gui_cert": { "title": "ConsoleSettingsResponseGui_Cert", "type": "object", "properties": { "source": { "type": "string" }, "subject": { "type": "string" }, "issuer": { "type": "string" }, "not_after": { "type": "string" }, "fingerprint_sha256": { "type": "string" } }, "required": [ "source", "subject", "issuer", "not_after", "fingerprint_sha256" ], "additionalProperties": true }, "telemetry_destination": { "title": "ConsoleSettingsResponseTelemetry_Destination", "type": "object", "properties": { "endpoint": { "type": [ "string", "null" ] }, "enabled": { "type": [ "boolean", "null" ] }, "source": { "type": "string" }, "effective_endpoint": { "type": "string" }, "effective_enabled": { "type": "boolean" } }, "required": [ "endpoint", "enabled", "source", "effective_endpoint", "effective_enabled" ], "additionalProperties": true } }, "required": [ "admin_username", "trust", "host_ip", "console_url", "gui_cert", "telemetry_destination" ], "additionalProperties": true }, "example": { "admin_username": "admin", "trust": [], "host_ip": "192.0.2.10", "console_url": "https://console.example.com:8080", "gui_cert": { "source": "built-in", "subject": "CN=console.example.com", "issuer": "CN=IRIS CA", "not_after": "Sep 4 00:00:00 2027 GMT", "fingerprint_sha256": "0000000000000000000000000000000000000000000000000000000000000000" }, "telemetry_destination": { "endpoint": null, "enabled": null, "source": "env", "effective_endpoint": "https://collector.example:4318", "effective_enabled": true } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/settings/peer-tls": { "get": { "operationId": "console_get_api_v1_settings_peer_tls", "summary": "Read peer transfer TLS mode", "description": "Read or change process-wide BitTorrent peer TLS. Defaults to disabled. Changes persist across restarts and restart the origin seeder automatically. New device onboarding inherits the mode. Existing agents must be undeployed and device jobs finished before a change (409 otherwise); re-onboard afterward. POST requires mode and expected_mode (disabled or required); stale expected_mode returns 409. Origin status is observed separately; saved mode is not proof of fleet encryption.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Configured mode and separately observed origin state", "content": { "application/json": { "schema": { "title": "PeerTlsSettings", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "disabled", "required" ] }, "origin": { "title": "PeerTlsSettingsOrigin", "type": "object", "properties": { "active_mode": { "type": [ "string", "null" ], "enum": [ "disabled", "required", null ] }, "state": { "type": "string" } }, "required": [ "active_mode", "state" ], "additionalProperties": true }, "active_devices": { "type": "integer" }, "active_jobs": { "type": "integer" }, "can_change": { "type": "boolean" } }, "required": [ "mode", "origin", "active_devices", "active_jobs", "can_change" ], "additionalProperties": true }, "example": { "mode": "disabled", "origin": { "active_mode": "disabled", "state": "running" }, "active_devices": 0, "active_jobs": 0, "can_change": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "console_post_api_v1_settings_peer_tls", "summary": "Set peer transfer TLS mode", "description": "Read or change process-wide BitTorrent peer TLS. Defaults to disabled. Changes persist across restarts and restart the origin seeder automatically. New device onboarding inherits the mode. Existing agents must be undeployed and device jobs finished before a change (409 otherwise); re-onboard afterward. POST requires mode and expected_mode (disabled or required); stale expected_mode returns 409. Origin status is observed separately; saved mode is not proof of fleet encryption.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Configured mode and separately observed origin state", "content": { "application/json": { "schema": { "title": "PeerTlsSettings", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "disabled", "required" ] }, "origin": { "title": "PeerTlsSettingsOrigin", "type": "object", "properties": { "active_mode": { "type": [ "string", "null" ], "enum": [ "disabled", "required", null ] }, "state": { "type": "string" } }, "required": [ "active_mode", "state" ], "additionalProperties": true }, "active_devices": { "type": "integer" }, "active_jobs": { "type": "integer" }, "can_change": { "type": "boolean" }, "applied": { "type": "boolean" } }, "required": [ "mode", "origin", "active_devices", "active_jobs", "can_change", "applied" ], "additionalProperties": true }, "example": { "mode": "disabled", "origin": { "active_mode": "disabled", "state": "running" }, "active_devices": 0, "active_jobs": 0, "can_change": true, "applied": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleSettingsPeerTlsRequest", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "disabled", "required" ] }, "expected_mode": { "type": "string", "enum": [ "disabled", "required" ] } }, "required": [ "mode", "expected_mode" ], "additionalProperties": false }, "example": { "mode": "required", "expected_mode": "disabled" } } } } } }, "/api/v1/settings/password": { "post": { "operationId": "console_post_api_v1_settings_password", "summary": "Change administrator password", "description": "Change administrator password. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Change administrator password response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsPasswordResponse", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleSettingsPasswordRequest", "type": "object", "properties": { "current": { "type": "string", "format": "password", "writeOnly": true }, "new": { "type": "string", "format": "password", "writeOnly": true }, "confirm": { "type": "string", "format": "password", "writeOnly": true } }, "required": [ "current", "new", "confirm" ], "additionalProperties": true }, "example": { "current": "current-password", "new": "new-password", "confirm": "new-password" } } } } } }, "/api/v1/settings/sessions/revoke-others": { "post": { "operationId": "console_post_api_v1_settings_sessions_revoke_others", "summary": "Revoke other sessions", "description": "Revoke other sessions. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Revoke other sessions response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsSessionsRevokeOthersResponse", "type": "object", "properties": { "revoked": { "type": "integer" } }, "required": [ "revoked" ], "additionalProperties": true }, "example": { "revoked": 2 } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleSettingsSessionsRevokeOthersRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/api/v1/settings/setup-status": { "get": { "operationId": "console_get_api_v1_settings_setup_status", "summary": "Read setup status", "description": "Read setup status. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read setup status response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsSetupStatusResponse", "type": "object", "properties": { "admin": { "title": "ConsoleSettingsSetupStatusResponseAdmin", "type": "object", "properties": { "state": { "type": "string" }, "username": { "type": "string" } }, "required": [ "state", "username" ], "additionalProperties": true }, "telemetry": { "title": "ConsoleSettingsSetupStatusResponseTelemetry", "type": "object", "properties": { "state": { "type": "string" }, "source": { "type": "string" }, "enabled": { "type": "boolean" }, "endpoint": { "type": "string", "format": "uri" } }, "required": [ "state", "source", "enabled", "endpoint" ], "additionalProperties": true }, "packages": { "title": "ConsoleSettingsSetupStatusResponsePackages", "type": "object", "properties": { "state": { "type": "string", "enum": [ "ok", "absent", "unknown", "stale" ] }, "reference_fingerprint": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "title": "ConsoleSettingsSetupStatusResponsePackagesItemsItem", "type": "object", "properties": { "name": { "type": "string" }, "state": { "type": "string", "enum": [ "ok", "absent", "unknown", "stale" ] }, "fingerprint": { "type": [ "string", "null" ], "description": "Null for deployment-neutral packages; runtime trust is reported by packages.reference_fingerprint." }, "built_at": { "type": [ "integer", "null" ], "description": "Artifact file modification time as Unix seconds; the field name does not attest the original package build time." }, "detail": { "type": "string" }, "remedy": { "type": "string" }, "provenance": { "type": [ "object", "null" ], "description": "Adjacent sidecar metadata bound to readable wrapper bytes. This check does not authenticate the sidecar or verify native signatures.", "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "properties": { "canonical_index_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "minLength": 71, "maxLength": 71 }, "canonical_archive_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "minLength": 64, "maxLength": 64 }, "canonical_source_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "minLength": 64, "maxLength": 64, "description": "Version 1 rooted build-context digest." } }, "required": [ "canonical_index_digest", "canonical_archive_sha256", "canonical_source_sha256" ] }, { "type": "object", "additionalProperties": false, "properties": { "canonical_index_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "minLength": 71, "maxLength": 71 }, "canonical_archive_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "minLength": 64, "maxLength": 64 }, "format": { "type": "string", "const": "iris-device-wrapper-v2" }, "canonical_neutral_source_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "minLength": 64, "maxLength": 64, "description": "Neutral build-context digest, not the version 1 rooted source digest." }, "canonical_finalization_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "minLength": 64, "maxLength": 64, "description": "Digest of the deployment-specific trust finalization record." } }, "required": [ "canonical_index_digest", "canonical_archive_sha256", "format", "canonical_neutral_source_sha256", "canonical_finalization_sha256" ] } ] }, "reason": { "type": "string" } }, "required": [ "name", "state", "fingerprint", "built_at", "remedy", "provenance" ], "additionalProperties": false } }, "remedy": { "type": "string" }, "reason": { "type": "string", "enum": [ "served-cert-unavailable", "distributed-cert-unavailable", "served-vs-distributed-mismatch" ] } }, "required": [ "state", "reference_fingerprint", "items", "remedy" ], "additionalProperties": true }, "image_verification": { "title": "ConsoleSettingsSetupStatusResponseImage_Verification", "type": "object", "properties": { "state": { "type": "string" } }, "required": [ "state" ], "additionalProperties": true } }, "required": [ "admin", "telemetry", "packages", "image_verification" ], "additionalProperties": true }, "example": { "admin": { "state": "ok", "username": "admin" }, "telemetry": { "state": "ok", "source": "env", "enabled": true, "endpoint": "https://collector.example:4318" }, "packages": { "state": "ok", "reference_fingerprint": "00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00", "items": [ { "name": "iris-amd64.tar", "state": "ok", "fingerprint": null, "built_at": 1788470400, "detail": "Package bytes match build provenance", "remedy": "tools/provision-iox-packages.sh", "provenance": { "canonical_index_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "canonical_archive_sha256": "1111111111111111111111111111111111111111111111111111111111111111", "canonical_source_sha256": "2222222222222222222222222222222222222222222222222222222222222222" } }, { "name": "iris-arm64.tar", "state": "ok", "fingerprint": null, "built_at": 1788470400, "detail": "Package bytes match build provenance", "remedy": "tools/provision-iox-packages.sh", "provenance": { "canonical_index_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "canonical_archive_sha256": "1111111111111111111111111111111111111111111111111111111111111111", "canonical_source_sha256": "2222222222222222222222222222222222222222222222222222222222222222" } }, { "name": "iris-xr.rpm", "state": "ok", "fingerprint": null, "built_at": 1788470400, "detail": "Package bytes match build provenance", "remedy": "tools/build-xr-package.sh --out artifacts/", "provenance": { "canonical_index_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "canonical_archive_sha256": "1111111111111111111111111111111111111111111111111111111111111111", "canonical_source_sha256": "2222222222222222222222222222222222222222222222222222222222222222" } }, { "name": "iris-agent.tgz", "state": "ok", "fingerprint": null, "built_at": 1788470400, "provenance": null, "reason": "ready", "detail": "Served Guest Shell files and embedded instruction trust match current startup provisioning.", "remedy": "Rebuild the server image and restart after correcting the provisioning error." } ], "remedy": "tools/provision-iox-packages.sh" }, "image_verification": { "state": "ok" } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/settings/certificates": { "get": { "operationId": "console_get_api_v1_settings_certificates", "summary": "Inspect server certificate validity", "description": "Inspect server certificate validity. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Inspect server certificate validity response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsCertificatesResponse", "type": "object", "properties": { "observed_at": { "type": "integer" }, "scope": { "type": "string" }, "items": { "type": "array", "items": { "title": "ConsoleSettingsCertificatesResponseItemsItem", "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "certificate", "public-key" ] }, "state": { "type": "string", "enum": [ "unknown", "within-validity", "not-yet-valid", "expired", "signing-refused", "renewal-due", "public-key-present" ] }, "source": { "type": "string" }, "fingerprint_sha256": { "type": [ "string", "null" ] }, "valid_from": { "type": [ "integer", "null" ] }, "expires_at": { "type": [ "integer", "null" ] }, "renew_at": { "type": [ "integer", "null" ] }, "refuse_at": { "type": [ "integer", "null" ] }, "impact": { "type": "string" } }, "required": [ "id", "label", "kind", "state", "source", "fingerprint_sha256", "valid_from", "expires_at", "renew_at", "refuse_at", "impact" ], "additionalProperties": true } }, "custody": { "type": [ "object", "null" ], "additionalProperties": true }, "note": { "type": "string" } }, "required": [ "observed_at", "scope", "items", "custody", "note" ], "additionalProperties": true }, "example": { "observed_at": 1788470400, "scope": "server-certificate-files", "items": [ { "id": "instruction-signer", "label": "Instruction signing certificate", "kind": "certificate", "state": "renewal-due", "source": "server-file", "fingerprint_sha256": "0000000000000000000000000000000000000000000000000000000000000000", "valid_from": 1787000000, "expires_at": 1789592000, "renew_at": 1788296000, "refuse_at": 1788987200, "impact": "Renew with offline root approval." } ], "custody": null, "note": "Validity dates do not prove trust, key availability or the certificate loaded by a listener." } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/settings/service-credentials": { "get": { "operationId": "console_get_api_v1_settings_service_credentials", "summary": "Read metrics and collector credential rotation", "description": "Read metrics and collector credential rotation. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read metrics and collector credential rotation response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "object", "properties": { "family": { "enum": [ "metrics-token", "collector-headers" ] }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "enum": [ "deployment-managed", "awaiting-verification", "completed", "reverted" ] }, "previous_retained": { "type": "boolean" }, "started_at": { "type": [ "integer", "null" ] }, "observed_at": { "type": [ "integer", "null" ] }, "endpoint": { "type": [ "string", "null" ] } }, "required": [ "family", "request_id", "state", "previous_retained", "started_at", "observed_at", "endpoint" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, "example": { "items": [ { "family": "metrics-token", "request_id": null, "state": "deployment-managed", "previous_retained": false, "started_at": null, "observed_at": null, "endpoint": null }, { "family": "collector-headers", "request_id": null, "state": "deployment-managed", "previous_retained": false, "started_at": null, "observed_at": null, "endpoint": null } ] } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "console_post_api_v1_settings_service_credentials", "summary": "Replace or retire metrics and collector credentials", "description": "Replace or retire metrics and collector credentials. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Replace or retire metrics and collector credentials response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "object", "properties": { "family": { "enum": [ "metrics-token", "collector-headers" ] }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "enum": [ "deployment-managed", "awaiting-verification", "completed", "reverted" ] }, "previous_retained": { "type": "boolean" }, "started_at": { "type": [ "integer", "null" ] }, "observed_at": { "type": [ "integer", "null" ] }, "endpoint": { "type": [ "string", "null" ] } }, "required": [ "family", "request_id", "state", "previous_retained", "started_at", "observed_at", "endpoint" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, "example": { "items": [ { "family": "metrics-token", "request_id": null, "state": "deployment-managed", "previous_retained": false, "started_at": null, "observed_at": null, "endpoint": null }, { "family": "collector-headers", "request_id": null, "state": "deployment-managed", "previous_retained": false, "started_at": null, "observed_at": null, "endpoint": null } ] } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "const": "replace" }, "family": { "const": "metrics-token" }, "request_id": { "type": "string", "format": "uuid" }, "confirm": { "const": true }, "token": { "type": "string", "minLength": 32, "maxLength": 256, "writeOnly": true } }, "required": [ "action", "family", "request_id", "confirm", "token" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "const": "replace" }, "family": { "const": "collector-headers" }, "request_id": { "type": "string", "format": "uuid" }, "confirm": { "const": true }, "headers": { "type": "object", "minProperties": 1, "maxProperties": 16, "writeOnly": true, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "endpoint": { "type": "string", "maxLength": 2048, "pattern": "^https://" } }, "required": [ "action", "family", "request_id", "confirm", "headers", "endpoint" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "enum": [ "retire", "revert" ] }, "family": { "enum": [ "metrics-token", "collector-headers" ] }, "request_id": { "type": "string", "format": "uuid" }, "confirm": { "const": true } }, "required": [ "action", "family", "request_id", "confirm" ], "additionalProperties": false } ] }, "example": { "action": "replace", "family": "metrics-token", "request_id": "00000000-0000-0000-0000-000000000001", "confirm": true, "token": "example-new-scrape-token-0123456789" } } } } } }, "/api/v1/settings/certificates/browser/rotation": { "get": { "operationId": "console_get_api_v1_settings_certificates_browser_rotation", "summary": "Read browser TLS rotation", "description": "Read browser TLS rotation. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read browser TLS rotation response", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "enum": [ "idle", "awaiting-approval", "approved", "committing", "published", "cancelled" ] }, "names": { "type": "array", "items": { "type": "string" } }, "mode": { "enum": [ null, "ca", "self-signed" ] }, "csr": { "type": [ "string", "null" ] }, "certificate": { "type": [ "string", "null" ] }, "created_at": { "type": [ "integer", "null" ] }, "fingerprint_sha256": { "type": [ "string", "null" ] } }, "required": [ "request_id", "state", "names", "mode", "csr", "certificate", "created_at", "fingerprint_sha256" ], "additionalProperties": false }, "example": { "request_id": null, "state": "idle", "names": [], "mode": null, "csr": null, "certificate": null, "created_at": null, "fingerprint_sha256": null } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "console_post_api_v1_settings_certificates_browser_rotation", "summary": "Prepare, approve or apply browser TLS rotation", "description": "Prepare, approve or apply browser TLS rotation. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Prepare, approve or apply browser TLS rotation response", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "enum": [ "idle", "awaiting-approval", "approved", "committing", "published", "cancelled" ] }, "names": { "type": "array", "items": { "type": "string" } }, "mode": { "enum": [ null, "ca", "self-signed" ] }, "csr": { "type": [ "string", "null" ] }, "certificate": { "type": [ "string", "null" ] }, "created_at": { "type": [ "integer", "null" ] }, "fingerprint_sha256": { "type": [ "string", "null" ] }, "applied": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "gui_cert": { "type": "object", "properties": { "source": { "type": "string" }, "subject": { "type": "string" }, "issuer": { "type": "string" }, "not_after": { "type": "string" }, "fingerprint_sha256": { "type": "string" } }, "required": [ "source", "subject", "issuer", "not_after", "fingerprint_sha256" ], "additionalProperties": false } }, "required": [ "request_id", "state", "names", "mode", "csr", "certificate", "created_at", "fingerprint_sha256" ], "additionalProperties": false }, "example": { "request_id": null, "state": "idle", "names": [], "mode": null, "csr": null, "certificate": null, "created_at": null, "fingerprint_sha256": null } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "const": "prepare" }, "request_id": { "type": "string", "format": "uuid" }, "names": { "type": "array", "minItems": 1, "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 253 } }, "mode": { "enum": [ "ca", "self-signed" ] } }, "required": [ "action", "request_id", "names", "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "const": "approve" }, "request_id": { "type": "string", "format": "uuid" }, "certificate": { "type": "string", "maxLength": 65536 } }, "required": [ "action", "request_id", "certificate" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "const": "apply" }, "request_id": { "type": "string", "format": "uuid" }, "confirm": { "const": true } }, "required": [ "action", "request_id", "confirm" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "const": "cancel" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "action", "request_id" ], "additionalProperties": false } ] }, "example": { "action": "prepare", "request_id": "00000000-0000-0000-0000-000000000001", "names": [ "console.example.com" ], "mode": "ca" } } } } } }, "/api/v1/settings/backups": { "get": { "operationId": "console_get_api_v1_settings_backups", "summary": "Read deployment backup worker status", "description": "Read deployment backup worker status. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "retention_request_id", "in": "query", "required": false, "description": "Observe the exact history-retirement or archive-deletion request after an uncertain response", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read deployment backup worker status response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsBackupsResponse", "type": "object", "properties": { "available": { "type": "boolean" }, "target": { "type": "string" }, "storage": { "type": "string" }, "can_verify": { "type": "boolean" }, "can_extract": { "type": "boolean" }, "can_restore": { "type": "boolean" }, "jobs": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "action", "backup_id", "state", "started_at", "detail" ], "properties": { "id": { "type": "string" }, "backup_id": { "type": "string" }, "action": { "enum": [ "backup", "verify", "extract", "restore" ] }, "state": { "enum": [ "running", "recovery-required", "captured", "failed", "verified-files", "verified-isolated-files", "restored", "refused" ] }, "started_at": { "type": "integer" }, "finished_at": { "type": "integer" }, "detail": { "type": "string" }, "proof": { "type": [ "object", "null" ], "additionalProperties": true } } } }, "note": { "type": "string" }, "retention": { "type": "object", "properties": { "schema": { "const": 1 }, "revision": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "busy": { "type": "boolean" }, "inventory_available": { "type": "boolean", "description": "False when unrecognized archive storage prevents a complete read-only inventory. Recovery job evidence remains available." }, "storage_problem": { "type": [ "string", "null" ], "maxLength": 1024 }, "recoverable_job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The sole interrupted operation that can be explicitly recovered; null while another maintenance action blocks it." }, "capacity": { "type": "object", "properties": { "history_used": { "type": "integer", "minimum": 0, "maximum": 100 }, "history_limit": { "const": 100 }, "backup_used": { "type": [ "integer", "null" ], "minimum": 0 }, "backup_limit": { "const": 20 }, "protected_upgrade_used": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "history_used", "history_limit", "backup_used", "backup_limit" ], "additionalProperties": false }, "jobs": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "state": { "type": "string" }, "backup_id": { "type": [ "string", "null" ], "format": "uuid" }, "family": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "integer", "null" ] }, "retire_allowed": { "type": "boolean" }, "retire_reason": { "type": "string" } }, "required": [ "id", "action", "state", "backup_id", "family", "finished_at", "retire_allowed", "retire_reason" ], "additionalProperties": false } }, "backups": { "type": "array", "items": { "type": "object", "properties": { "backup_id": { "type": "string", "format": "uuid" }, "created_at": { "type": [ "integer", "null" ] }, "delete_allowed": { "type": "boolean" }, "delete_reason": { "type": "string" } }, "required": [ "backup_id", "created_at", "delete_allowed", "delete_reason" ], "additionalProperties": false } }, "protected_upgrade_backups": { "type": "array", "items": { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid" }, "attempt": { "type": "integer", "minimum": 1, "maximum": 3 }, "phase": { "enum": [ "building", "prepared", "fencing", "backing-up", "stopped", "publishing", "published", "starting", "verifying", "worker", "finishing", "upgraded", "cancelled", "recovery-required" ] }, "deployment_archive": { "type": "boolean" }, "recovery_archive": { "type": "boolean" } }, "required": [ "operation_id", "attempt", "phase", "deployment_archive", "recovery_archive" ], "additionalProperties": false } }, "operation": { "oneOf": [ { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "action": { "enum": [ "retire-history", "delete-backup" ] }, "state": { "enum": [ "running", "completed", "recovery-required" ] }, "retired_count": { "type": "integer", "minimum": 0, "maximum": 100 }, "backup_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "request_id", "action", "state", "retired_count", "backup_id" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "schema", "revision", "busy", "capacity", "jobs", "backups", "operation" ], "additionalProperties": false, "dependentRequired": { "inventory_available": [ "storage_problem" ], "storage_problem": [ "inventory_available" ] }, "allOf": [ { "if": { "properties": { "inventory_available": { "const": false } }, "required": [ "inventory_available" ] }, "then": { "required": [ "protected_upgrade_backups" ], "properties": { "storage_problem": { "type": "string", "minLength": 1 }, "capacity": { "required": [ "protected_upgrade_used" ], "properties": { "backup_used": { "type": "null" }, "protected_upgrade_used": { "type": "null" } } }, "backups": { "maxItems": 0 }, "protected_upgrade_backups": { "maxItems": 0 }, "jobs": { "items": { "properties": { "retire_allowed": { "const": false } } } } } }, "else": { "properties": { "storage_problem": { "type": "null" }, "capacity": { "properties": { "backup_used": { "type": "integer" }, "protected_upgrade_used": { "type": "integer" } } } } } } ] }, "can_recover_backup": { "type": "boolean", "description": "Whether this managed worker supports recovery of its recorded interrupted backups." }, "restore_scope": { "type": "string", "enum": [ "same-deployment-same-security-generation" ] } }, "required": [ "available", "target", "storage", "can_verify", "can_extract", "can_restore", "jobs", "note" ], "additionalProperties": true }, "example": { "available": false, "target": "unavailable", "storage": "unavailable", "can_verify": false, "can_extract": false, "can_restore": false, "jobs": [], "note": "Configure the lifecycle worker on the installer host." } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "console_post_api_v1_settings_backups", "summary": "Request backup, verification, extraction, restore or recovery, history retirement or exact archive deletion", "description": "Request backup, verification, extraction, restore or recovery, history retirement or exact archive deletion. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Request backup, verification, extraction, restore or recovery, history retirement or exact archive deletion response", "content": { "application/json": { "schema": { "oneOf": [ { "title": "ConsoleSettingsBackupsResponse", "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ], "additionalProperties": true }, { "type": "object", "properties": { "retention_operation": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "action": { "enum": [ "retire-history", "delete-backup" ] }, "state": { "enum": [ "running", "completed", "recovery-required" ] }, "retired_count": { "type": "integer", "minimum": 0, "maximum": 100 }, "backup_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "request_id", "action", "state", "retired_count", "backup_id" ], "additionalProperties": false } }, "required": [ "retention_operation" ], "additionalProperties": false } ] }, "example": { "job_id": "00000000-0000-0000-0000-000000000001" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "action", "allow_downtime", "request_id" ], "properties": { "action": { "const": "backup" }, "allow_downtime": { "const": true }, "request_id": { "type": "string", "pattern": "^[0-9a-f-]{36}$" } } }, { "type": "object", "properties": { "action": { "const": "recover-backup" }, "request_id": { "type": "string", "format": "uuid" }, "backup_id": { "type": "string", "format": "uuid" }, "allow_downtime": { "const": true } }, "required": [ "action", "request_id", "backup_id", "allow_downtime" ], "additionalProperties": false }, { "type": "object", "additionalProperties": false, "required": [ "action", "backup_id", "request_id" ], "properties": { "action": { "enum": [ "verify", "extract" ] }, "backup_id": { "type": "string", "pattern": "^[0-9a-f-]{36}$" }, "request_id": { "type": "string", "pattern": "^[0-9a-f-]{36}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "action", "backup_id", "request_id", "allow_downtime", "confirm_restore" ], "properties": { "action": { "enum": [ "restore", "recover-restore" ] }, "backup_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "allow_downtime": { "const": true }, "confirm_restore": { "const": true } } }, { "type": "object", "properties": { "action": { "const": "retire-history" }, "request_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "job_ids": { "type": "array", "minItems": 1, "maxItems": 25, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } } }, "required": [ "action", "request_id", "expected_revision", "job_ids" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "enum": [ "delete-backup", "resume-delete" ] }, "request_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "backup_id": { "type": "string", "format": "uuid" }, "confirm_delete": { "const": true } }, "required": [ "action", "request_id", "expected_revision", "backup_id", "confirm_delete" ], "additionalProperties": false } ] }, "example": { "action": "backup", "allow_downtime": true, "request_id": "00000000-0000-0000-0000-000000000001" } } } } } }, "/api/v1/settings/deployment-rotation": { "get": { "operationId": "console_get_api_v1_settings_deployment_rotation", "summary": "Read deployment credential maintenance evidence", "description": "Read deployment credential maintenance evidence. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read deployment credential maintenance evidence response", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "target": { "enum": [ "single-docker", "split-docker", "kubernetes", "unavailable" ] }, "can_rotate": { "type": "boolean" }, "note": { "type": "string" }, "families": { "type": "array", "items": { "enum": [ "management-tls", "device-tls", "peer-ca", "instruction-roots", "age-identity", "age-recovery", "seeder-announce" ] } }, "jobs": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "action", "family", "state", "started_at", "detail", "proof" ], "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "const": "rotate" }, "family": { "type": "string" }, "state": { "type": "string" }, "started_at": { "type": "integer" }, "finished_at": { "type": "integer" }, "detail": { "type": "string" }, "proof": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "management_https": { "const": "verified" }, "certificate_sha256": { "type": "string" }, "console_consumers": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "pod_uid": { "type": "string" }, "certificate_sha256": { "type": "string" }, "management_https": { "const": "verified" } }, "required": [ "pod_uid", "certificate_sha256", "management_https" ], "additionalProperties": false } }, "dedicated_management_key": { "const": "verified" }, "age_files": { "type": "integer" }, "service_recipient": { "type": "string" }, "recovery_recipient": { "type": "string" }, "independent_decryption": { "const": "verified" }, "seeded_torrents": { "type": "integer" }, "credential_changed": { "const": true }, "isolated_tracker_proof": { "const": "verified" }, "restarted_tracker_proof": { "const": "verified" }, "family": { "enum": [ "device-tls", "peer-ca", "instruction-roots" ] }, "request_id": { "type": "string", "format": "uuid" }, "packages_verified": { "const": true }, "device_consumers": { "const": "re-onboarding-required" }, "catalog_tls_sha256": { "type": "string" }, "peer_ca_sha256": { "type": "string" }, "origin_mode": { "enum": [ "required", "disabled" ] }, "root_sha256": { "type": "object", "additionalProperties": { "type": "string" } }, "keylist_seq": { "type": "integer" } } } } } } }, "required": [ "available", "target", "can_rotate", "note", "families", "jobs" ], "additionalProperties": false }, "example": { "available": false, "target": "unavailable", "can_rotate": false, "families": [], "jobs": [], "note": "Configure deployment maintenance and recovery access." } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "console_post_api_v1_settings_deployment_rotation", "summary": "Request verified-backup credential maintenance", "description": "Request verified-backup credential maintenance. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Request verified-backup credential maintenance response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsDeploymentRotationResponse", "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ], "additionalProperties": true }, "example": { "job_id": "00000000-0000-0000-0000-000000000001" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "enum": [ "rotate", "recover-rotation" ] }, "allow_downtime": { "const": true }, "request_id": { "type": "string", "format": "uuid" }, "family": { "enum": [ "management-tls", "device-tls", "peer-ca", "instruction-roots", "age-identity", "age-recovery", "seeder-announce" ] } }, "required": [ "action", "allow_downtime", "request_id", "family" ], "additionalProperties": false }, "example": { "action": "rotate", "allow_downtime": true, "request_id": "00000000-0000-0000-0000-000000000001", "family": "management-tls" } } } } } }, "/api/v1/settings/trust-rotation": { "get": { "operationId": "console_get_api_v1_settings_trust_rotation", "summary": "Read public deployment trust approvals", "description": "Read public deployment trust approvals. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read public deployment trust approvals response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": "object", "properties": { "family": { "enum": [ "device-tls", "peer-ca", "instruction-roots" ] }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "enum": [ "idle", "awaiting-approval", "approved", "committing", "published", "cancelled" ] }, "created_at": { "type": [ "integer", "null" ] }, "names": { "type": "array", "items": { "type": "string" } }, "mode": { "type": [ "string", "null" ] }, "csr": { "type": [ "string", "null" ] }, "certificate": { "type": [ "string", "null" ] }, "fingerprint_sha256": { "type": [ "string", "null" ] }, "roots": { "type": "object", "additionalProperties": { "type": "string" } }, "online_public_key": { "type": [ "string", "null" ] }, "keylist_payload": { "type": [ "string", "null" ] }, "keylist_signer": { "type": [ "string", "null" ] }, "requires_reonboarding": { "type": "boolean" }, "requires_package_rebuild": { "type": "boolean" }, "attestation_request_id": { "type": [ "string", "null" ], "format": "uuid" }, "attestation_root_id": { "type": [ "string", "null" ] }, "attested_root_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "family", "request_id", "state", "created_at", "names", "mode", "csr", "certificate", "fingerprint_sha256", "roots", "online_public_key", "keylist_payload", "keylist_signer", "requires_reonboarding", "requires_package_rebuild", "attestation_request_id", "attestation_root_id", "attested_root_ids" ], "additionalProperties": false } }, "drain": { "type": "object", "properties": { "ready": { "type": "boolean" }, "blocked_device_ids": { "type": "array", "items": { "type": "string" } }, "removed_device_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "ready", "blocked_device_ids", "removed_device_ids" ], "additionalProperties": false } }, "required": [ "items", "drain" ], "additionalProperties": false }, "example": { "items": [ { "family": "device-tls", "request_id": null, "state": "idle", "created_at": null, "names": [], "mode": null, "csr": null, "certificate": null, "fingerprint_sha256": null, "roots": {}, "online_public_key": null, "keylist_payload": null, "keylist_signer": null, "requires_reonboarding": true, "requires_package_rebuild": false, "attested_root_ids": [], "attestation_request_id": null, "attestation_root_id": null }, { "family": "peer-ca", "request_id": null, "state": "idle", "created_at": null, "names": [], "mode": null, "csr": null, "certificate": null, "fingerprint_sha256": null, "roots": {}, "online_public_key": null, "keylist_payload": null, "keylist_signer": null, "requires_reonboarding": true, "requires_package_rebuild": false, "attested_root_ids": [], "attestation_request_id": null, "attestation_root_id": null }, { "family": "instruction-roots", "request_id": null, "state": "idle", "created_at": null, "names": [], "mode": null, "csr": null, "certificate": null, "fingerprint_sha256": null, "roots": {}, "online_public_key": null, "keylist_payload": null, "keylist_signer": null, "requires_reonboarding": true, "requires_package_rebuild": true, "attested_root_ids": [], "attestation_request_id": null, "attestation_root_id": null } ], "drain": { "ready": true, "blocked_device_ids": [], "removed_device_ids": [] } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "console_post_api_v1_settings_trust_rotation", "summary": "Prepare or approve deployment trust without publishing", "description": "Prepare or approve deployment trust without publishing. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Prepare or approve deployment trust without publishing response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "family": { "enum": [ "device-tls", "peer-ca", "instruction-roots" ] }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "enum": [ "idle", "awaiting-approval", "approved", "committing", "published", "cancelled" ] }, "created_at": { "type": [ "integer", "null" ] }, "names": { "type": "array", "items": { "type": "string" } }, "mode": { "type": [ "string", "null" ] }, "csr": { "type": [ "string", "null" ] }, "certificate": { "type": [ "string", "null" ] }, "fingerprint_sha256": { "type": [ "string", "null" ] }, "roots": { "type": "object", "additionalProperties": { "type": "string" } }, "online_public_key": { "type": [ "string", "null" ] }, "keylist_payload": { "type": [ "string", "null" ] }, "keylist_signer": { "type": [ "string", "null" ] }, "requires_reonboarding": { "type": "boolean" }, "requires_package_rebuild": { "type": "boolean" }, "attestation_request_id": { "type": [ "string", "null" ], "format": "uuid" }, "attestation_root_id": { "type": [ "string", "null" ] }, "attested_root_ids": { "type": "array", "items": { "type": "string" } }, "attestation_applied": { "const": true, "description": "Present only after the signed current-root attestation was installed and verified." } }, "required": [ "family", "request_id", "state", "created_at", "names", "mode", "csr", "certificate", "fingerprint_sha256", "roots", "online_public_key", "keylist_payload", "keylist_signer", "requires_reonboarding", "requires_package_rebuild", "attestation_request_id", "attestation_root_id", "attested_root_ids" ], "additionalProperties": false }, { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "root_id": { "type": "string" }, "payload": { "type": "string" } }, "required": [ "request_id", "root_id", "payload" ], "additionalProperties": false } ] }, "example": { "family": "peer-ca", "request_id": null, "state": "idle", "created_at": null, "names": [], "mode": null, "csr": null, "certificate": null, "fingerprint_sha256": null, "roots": {}, "online_public_key": null, "keylist_payload": null, "keylist_signer": null, "requires_reonboarding": true, "requires_package_rebuild": false, "attested_root_ids": [], "attestation_request_id": null, "attestation_root_id": null } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "family": { "const": "device-tls" }, "action": { "const": "prepare" }, "request_id": { "type": "string", "format": "uuid" }, "names": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "maxLength": 253 } }, "mode": { "enum": [ "ca", "self-signed" ] } }, "required": [ "family", "action", "request_id", "names", "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "peer-ca" }, "action": { "const": "prepare" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "family", "action", "request_id" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "instruction-roots" }, "action": { "const": "prepare" }, "request_id": { "type": "string", "format": "uuid" }, "roots": { "type": "object", "minProperties": 2, "maxProperties": 2, "additionalProperties": { "type": "string", "maxLength": 4096 } }, "keylist_signer": { "type": "string", "maxLength": 64 } }, "required": [ "family", "action", "request_id", "roots", "keylist_signer" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "device-tls" }, "action": { "const": "approve" }, "request_id": { "type": "string", "format": "uuid" }, "certificate": { "type": "string", "maxLength": 65536 } }, "required": [ "family", "action", "request_id", "certificate" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "instruction-roots" }, "action": { "const": "approve" }, "request_id": { "type": "string", "format": "uuid" }, "certificate": { "type": "string", "maxLength": 65536 }, "keylist": { "type": "string", "maxLength": 174764 } }, "required": [ "family", "action", "request_id", "certificate", "keylist" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "instruction-roots" }, "action": { "const": "attestation-request" }, "request_id": { "type": "string", "format": "uuid" }, "root_id": { "type": "string", "maxLength": 64 } }, "required": [ "family", "action", "request_id", "root_id" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "instruction-roots" }, "action": { "const": "attestation-apply" }, "request_id": { "type": "string", "format": "uuid" }, "root_id": { "type": "string", "maxLength": 64 }, "keylist": { "type": "string", "maxLength": 174764 } }, "required": [ "family", "action", "request_id", "root_id", "keylist" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "device-tls" }, "action": { "const": "cancel" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "family", "action", "request_id" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "peer-ca" }, "action": { "const": "cancel" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "family", "action", "request_id" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "instruction-roots" }, "action": { "const": "cancel" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "family", "action", "request_id" ], "additionalProperties": false } ] }, "example": { "action": "prepare", "family": "peer-ca", "request_id": "00000000-0000-0000-0000-000000000001" } } } } } }, "/api/v1/settings/certificates/instruction/request": { "post": { "operationId": "console_post_api_v1_settings_certificates_instruction_request", "summary": "Prepare public instruction certificate renewal", "description": "Prepare public instruction certificate renewal. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Prepare public instruction certificate renewal response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsCertificatesInstructionRequestResponse", "type": "object", "properties": { "public_key": { "type": "string" }, "public_key_sha256": { "type": "string" }, "certificate_sha256": { "type": "string" } }, "required": [ "public_key", "public_key_sha256", "certificate_sha256" ], "additionalProperties": true }, "example": { "public_key": "ssh-ed25519 ...", "public_key_sha256": "0000000000000000000000000000000000000000000000000000000000000000", "certificate_sha256": "1111111111111111111111111111111111111111111111111111111111111111" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleSettingsCertificatesInstructionRequestRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } } } }, "/api/v1/settings/certificates/instruction/renew": { "post": { "operationId": "console_post_api_v1_settings_certificates_instruction_renew", "summary": "Renew the existing instruction signing certificate", "description": "Renew the existing instruction signing certificate. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Renew the existing instruction signing certificate response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsCertificatesInstructionRenewResponse", "type": "object", "properties": { "applied": { "type": "boolean" }, "expires_at": { "type": "integer" }, "refuse_at": { "type": "integer" }, "status_refreshed": { "type": "boolean" } }, "required": [ "applied", "expires_at", "refuse_at", "status_refreshed" ], "additionalProperties": true }, "example": { "applied": true, "expires_at": 1789592000, "refuse_at": 1788987200, "status_refreshed": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleSettingsCertificatesInstructionRenewRequest", "type": "object", "properties": { "certificate": { "type": "string", "maxLength": 65536 }, "public_key_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "certificate_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "certificate", "public_key_sha256", "certificate_sha256" ], "additionalProperties": false }, "example": { "certificate": "ssh-ed25519-cert-v01@openssh.com ...", "public_key_sha256": "0000000000000000000000000000000000000000000000000000000000000000", "certificate_sha256": "1111111111111111111111111111111111111111111111111111111111111111" } } } } } }, "/api/v1/settings/certificates/instruction/rotation": { "get": { "operationId": "console_get_api_v1_settings_certificates_instruction_rotation", "summary": "Inspect online signer rotation", "description": "Inspect online signer rotation. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Inspect online signer rotation response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsCertificatesInstructionRotationResponse", "type": "object", "properties": { "state": { "enum": [ "idle", "awaiting-approval", "committing", "retirement-pending", "retiring", "completed", "cancelled" ] }, "request_id": { "type": [ "string", "null" ] }, "previous_public_key": { "type": [ "string", "null" ] }, "public_key": { "type": [ "string", "null" ] }, "previous_sha256": { "type": [ "string", "null" ] }, "replacement_sha256": { "type": [ "string", "null" ] }, "created_at": { "type": [ "integer", "null" ] }, "activated_at": { "type": [ "integer", "null" ] }, "retired_keylist_seq": { "type": [ "integer", "null" ] }, "root_ids": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } }, "required": [ "state", "request_id", "previous_public_key", "public_key", "previous_sha256", "replacement_sha256", "created_at", "activated_at", "retired_keylist_seq", "root_ids", "note" ], "additionalProperties": false }, "example": { "state": "idle", "request_id": null, "previous_public_key": null, "public_key": null, "previous_sha256": null, "replacement_sha256": null, "created_at": null, "activated_at": null, "retired_keylist_seq": null, "root_ids": [ "root-a", "root-b" ], "note": "Server-side evidence; confirm device acceptance separately." } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "console_post_api_v1_settings_certificates_instruction_rotation", "summary": "Prepare, activate or retire an online signer", "description": "Prepare, activate or retire an online signer. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Prepare, activate or retire an online signer response", "content": { "application/json": { "schema": { "oneOf": [ { "title": "ConsoleSettingsCertificatesInstructionRotationResponse", "type": "object", "properties": { "state": { "enum": [ "idle", "awaiting-approval", "committing", "retirement-pending", "retiring", "completed", "cancelled" ] }, "request_id": { "type": [ "string", "null" ] }, "previous_public_key": { "type": [ "string", "null" ] }, "public_key": { "type": [ "string", "null" ] }, "previous_sha256": { "type": [ "string", "null" ] }, "replacement_sha256": { "type": [ "string", "null" ] }, "created_at": { "type": [ "integer", "null" ] }, "activated_at": { "type": [ "integer", "null" ] }, "retired_keylist_seq": { "type": [ "integer", "null" ] }, "root_ids": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } }, "required": [ "state", "request_id", "previous_public_key", "public_key", "previous_sha256", "replacement_sha256", "created_at", "activated_at", "retired_keylist_seq", "root_ids", "note" ], "additionalProperties": false }, { "type": "object", "additionalProperties": false, "required": [ "request_id", "payload", "root_id" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "payload": { "type": "string" }, "root_id": { "type": "string" } } } ] }, "example": { "state": "idle", "request_id": null, "previous_public_key": null, "public_key": null, "previous_sha256": null, "replacement_sha256": null, "created_at": null, "activated_at": null, "retired_keylist_seq": null, "root_ids": [ "root-a", "root-b" ], "note": "Server-side evidence; confirm device acceptance separately." } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "action": { "const": "prepare" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "action", "request_id" ] }, { "type": "object", "additionalProperties": false, "properties": { "action": { "const": "cancel" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "action", "request_id" ] }, { "type": "object", "additionalProperties": false, "properties": { "action": { "const": "activate" }, "request_id": { "type": "string", "format": "uuid" }, "certificate": { "type": "string", "maxLength": 65536 }, "confirm": { "const": true } }, "required": [ "action", "request_id", "certificate", "confirm" ] }, { "type": "object", "additionalProperties": false, "properties": { "action": { "const": "retirement-request" }, "request_id": { "type": "string", "format": "uuid" }, "root_id": { "type": "string", "maxLength": 64 } }, "required": [ "action", "request_id", "root_id" ] }, { "type": "object", "additionalProperties": false, "properties": { "action": { "const": "retire" }, "request_id": { "type": "string", "format": "uuid" }, "artifact": { "type": "string", "maxLength": 174764 }, "confirm": { "const": true } }, "required": [ "action", "request_id", "artifact", "confirm" ] } ] }, "example": { "action": "prepare", "request_id": "00000000-0000-0000-0000-000000000001" } } } } } }, "/api/v1/settings/image-verification": { "get": { "operationId": "console_get_api_v1_settings_image_verification", "summary": "Read verification settings", "description": "Read verification settings. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read verification settings response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsImageVerificationResponse", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "daily", "weekly" ] }, "hour_utc": { "type": "integer", "minimum": 0, "maximum": 23 }, "last_run": { "title": "ConsoleSettingsImageVerificationResponseLast_Run", "type": "object", "properties": { "at": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "outcome": { "type": [ "string", "null" ] }, "matched": { "type": [ "integer", "null" ] }, "mismatched": { "type": [ "integer", "null" ] }, "not_in_feed": { "type": [ "integer", "null" ] } }, "required": [ "at", "source", "outcome", "matched", "mismatched", "not_in_feed" ], "additionalProperties": true } }, "required": [ "mode", "hour_utc", "last_run" ], "additionalProperties": true }, "example": { "mode": "daily", "hour_utc": 3, "last_run": { "at": null, "source": null, "outcome": null, "matched": null, "mismatched": null, "not_in_feed": null } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "console_post_api_v1_settings_image_verification", "summary": "Update verification settings", "description": "Update verification settings. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Update verification settings response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsImageVerificationResponse", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "daily", "weekly" ] }, "hour_utc": { "type": "integer", "minimum": 0, "maximum": 23 }, "last_run": { "title": "ConsoleSettingsImageVerificationResponseLast_Run", "type": "object", "properties": { "at": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "outcome": { "type": [ "string", "null" ] }, "matched": { "type": [ "integer", "null" ] }, "mismatched": { "type": [ "integer", "null" ] }, "not_in_feed": { "type": [ "integer", "null" ] } }, "required": [ "at", "source", "outcome", "matched", "mismatched", "not_in_feed" ], "additionalProperties": true } }, "required": [ "mode", "hour_utc", "last_run" ], "additionalProperties": true }, "example": { "mode": "daily", "hour_utc": 3, "last_run": { "at": null, "source": null, "outcome": null, "matched": null, "mismatched": null, "not_in_feed": null } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleSettingsImageVerificationRequest", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "daily", "weekly" ] }, "hour_utc": { "type": "integer", "minimum": 0, "maximum": 23 } }, "required": [ "mode" ], "additionalProperties": true }, "example": { "mode": "daily", "hour_utc": 3 } } } } } }, "/api/v1/settings/audit-export": { "post": { "operationId": "console_post_api_v1_settings_audit_export", "summary": "Update audit export settings", "description": "Update audit export settings. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Update audit export settings response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsAuditExportResponse", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleSettingsAuditExportRequest", "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "integer" }, "user": { "type": "string" }, "path": { "type": "string" }, "age_recipient": { "type": "string" }, "auto": { "type": "boolean" }, "password": { "type": "string", "format": "password", "writeOnly": true, "description": "Required for first configuration or recovery after an interrupted save/clear leaves the destination unconfigured. An absent or empty password keeps the stored secret only when the existing configuration is valid. Must not contain U+0000 (NUL)." } }, "required": [ "host", "user", "path", "age_recipient" ], "additionalProperties": true }, "example": { "host": "audit.example", "port": 22, "user": "iris", "path": "/archive/iris", "age_recipient": "age1example", "auto": true, "password": "transport-password" } } } } }, "delete": { "operationId": "console_delete_api_v1_settings_audit_export", "summary": "Delete audit export settings", "description": "Delete audit export settings. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Delete audit export settings response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsAuditExportResponse", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": true }, "example": { "deleted": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/settings/audit-export/run": { "post": { "operationId": "console_post_api_v1_settings_audit_export_run", "summary": "Start audit export", "description": "Start audit export. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Start audit export response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsAuditExportRunResponse", "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ], "additionalProperties": true }, "example": { "job_id": "job-01" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleSettingsAuditExportRunRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/api/v1/settings/audit-export/run/{job_id}": { "get": { "operationId": "console_get_api_v1_settings_audit_export_run_job_id", "summary": "Read audit export job", "description": "Read audit export job. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" } ], "responses": { "200": { "description": "Read audit export job response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsAuditExportRunJobIdResponse", "type": "object", "properties": { "state": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "state", "detail" ], "additionalProperties": true }, "example": { "state": "running", "detail": "" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API" } }, "/api/v1/settings/ca-trust": { "post": { "operationId": "console_post_api_v1_settings_ca_trust", "summary": "Update CA trust settings", "description": "Update CA trust settings. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Update CA trust settings response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsCaTrustResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "ca_trust": { "title": "ConsoleSettingsCaTrustResponseCa_Trust", "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "auto": { "type": "boolean" } }, "required": [ "url", "auto" ], "additionalProperties": true } }, "required": [ "ok", "ca_trust" ], "additionalProperties": true }, "example": { "ok": true, "ca_trust": { "url": "https://example.invalid/ca.pem", "auto": true } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleSettingsCaTrustRequest", "type": "object", "properties": { "url": { "type": [ "string", "null" ], "format": "uri" }, "auto": { "type": "boolean" } }, "required": [], "additionalProperties": true }, "example": { "url": null, "auto": true } } } } } }, "/api/v1/settings/ca-trust/refresh": { "post": { "operationId": "console_post_api_v1_settings_ca_trust_refresh", "summary": "Start CA trust refresh", "description": "Start CA trust refresh. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Start CA trust refresh response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsCaTrustRefreshResponse", "type": "object", "properties": { "job": { "type": "string" } }, "required": [ "job" ], "additionalProperties": true }, "example": { "job": "job-01" } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleSettingsCaTrustRefreshRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/api/v1/settings/ca-trust/refresh/{job_id}": { "get": { "operationId": "console_get_api_v1_settings_ca_trust_refresh_job_id", "summary": "Read CA trust refresh job", "description": "Read CA trust refresh job. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" } ], "responses": { "200": { "description": "Read CA trust refresh job response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsCaTrustRefreshJobIdResponse", "type": "object", "properties": { "state": { "type": "string" }, "detail": { "type": "string" }, "certs": { "type": [ "integer", "null" ] } }, "required": [ "state", "detail", "certs" ], "additionalProperties": true }, "example": { "state": "running", "detail": "", "certs": null } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API" } }, "/api/v1/settings/telemetry-destination": { "post": { "operationId": "console_post_api_v1_settings_telemetry_destination", "summary": "Update telemetry destination", "description": "Update telemetry destination. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Update telemetry destination response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsTelemetryDestinationResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "endpoint": { "type": [ "string", "null" ], "format": "uri" }, "enabled": { "type": [ "boolean", "null" ] } }, "required": [ "ok", "endpoint", "enabled" ], "additionalProperties": true }, "example": { "ok": true, "endpoint": null, "enabled": null } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ConsoleSettingsTelemetryDestinationRequest", "type": "object", "properties": { "endpoint": { "type": [ "string", "null" ], "format": "uri" }, "enabled": { "type": [ "boolean", "null" ] } }, "required": [], "additionalProperties": true }, "example": { "endpoint": null, "enabled": null } } } } }, "delete": { "operationId": "console_delete_api_v1_settings_telemetry_destination", "summary": "Delete telemetry destination", "description": "Delete telemetry destination. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Delete telemetry destination response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsTelemetryDestinationResponse", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": true }, "example": { "deleted": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/settings/gui-cert": { "post": { "operationId": "console_post_api_v1_settings_gui_cert", "summary": "Install console certificate", "description": "Install console certificate. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Successful changes persist on the server and reload this Console before replying. applied reports the Console reload result; gui_cert describes the identity currently loaded. If applied is false, restart the Console to load the saved configuration.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Install console certificate response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsGuiCertResponse", "type": "object", "properties": { "gui_cert": { "title": "ConsoleSettingsGuiCertResponseGui_Cert", "type": "object", "properties": { "source": { "type": "string" }, "subject": { "type": "string" }, "issuer": { "type": "string" }, "not_after": { "type": "string" }, "fingerprint_sha256": { "type": "string" } }, "required": [ "source", "subject", "issuer", "not_after", "fingerprint_sha256" ], "additionalProperties": true }, "applied": { "type": "boolean" }, "note": { "type": [ "string", "null" ] } }, "required": [ "gui_cert", "applied", "note" ], "additionalProperties": true }, "example": { "gui_cert": { "source": "custom", "subject": "CN=iris.example", "issuer": "CN=IRIS CA", "not_after": "Sep 4 00:00:00 2027 GMT", "fingerprint_sha256": "0000000000000000000000000000000000000000000000000000000000000000" }, "applied": true, "note": null } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleSettingsGuiCertRequest", "type": "object", "properties": { "cert_pem": { "type": "string" }, "key_pem": { "type": "string" }, "key_passphrase": { "type": "string", "format": "password", "writeOnly": true } }, "required": [ "cert_pem", "key_pem" ], "additionalProperties": true }, "example": { "cert_pem": "-----BEGIN CERTIFICATE-----\n...", "key_pem": "-----BEGIN PRIVATE KEY-----\n...", "key_passphrase": "optional-passphrase" } } } } }, "delete": { "operationId": "console_delete_api_v1_settings_gui_cert", "summary": "Remove console certificate", "description": "Remove console certificate. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Successful changes persist on the server and reload this Console before replying. applied reports the Console reload result; gui_cert describes the identity currently loaded. If applied is false, restart the Console to load the saved configuration.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Remove console certificate response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsGuiCertResponse", "type": "object", "properties": { "deleted": { "type": "boolean" }, "applied": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "gui_cert": { "title": "ConsoleSettingsGuiCertResponseGui_Cert", "type": "object", "properties": { "source": { "type": "string" }, "subject": { "type": "string" }, "issuer": { "type": "string" }, "not_after": { "type": "string" }, "fingerprint_sha256": { "type": "string" } }, "required": [ "source", "subject", "issuer", "not_after", "fingerprint_sha256" ], "additionalProperties": true } }, "required": [ "deleted", "applied", "note", "gui_cert" ], "additionalProperties": true }, "example": { "deleted": true, "applied": true, "note": null, "gui_cert": { "source": "built-in", "subject": "CN=iris.example", "issuer": "CN=IRIS CA", "not_after": "Sep 4 00:00:00 2027 GMT", "fingerprint_sha256": "0000000000000000000000000000000000000000000000000000000000000000" } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/settings/trust": { "post": { "operationId": "console_post_api_v1_settings_trust", "summary": "Install a trust anchor", "description": "Install a trust anchor. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Install a trust anchor response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsTrustResponse", "type": "object", "properties": { "entry": { "title": "ConsoleSettingsTrustResponseEntry", "type": "object", "properties": { "name": { "type": "string" }, "subject": { "type": "string" }, "fingerprint_sha256": { "type": "string" } }, "required": [ "name", "subject", "fingerprint_sha256" ], "additionalProperties": true } }, "required": [ "entry" ], "additionalProperties": true }, "example": { "entry": { "name": "ca-example.pem", "subject": "CN=Example CA", "fingerprint_sha256": "0000000000000000000000000000000000000000000000000000000000000000" } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ConsoleSettingsTrustRequest", "type": "object", "properties": { "pem": { "type": "string" } }, "required": [ "pem" ], "additionalProperties": true }, "example": { "pem": "-----BEGIN CERTIFICATE-----\n..." } } } } } }, "/api/v1/settings/trust/{name}": { "delete": { "operationId": "console_delete_api_v1_settings_trust_name", "summary": "Delete a trust anchor", "description": "Delete a trust anchor. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Delete a trust anchor response", "content": { "application/json": { "schema": { "title": "ConsoleSettingsTrustNameResponse", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": true }, "example": { "deleted": true } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/help": { "get": { "operationId": "console_get_api_v1_help", "summary": "Read help metadata", "description": "Read help metadata. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read help metadata response", "content": { "application/json": { "schema": { "title": "ConsoleHelpResponse", "type": "object", "properties": { "version": { "type": "string" }, "deployment_id": { "type": "string" }, "docs_url": { "type": "string", "format": "uri" }, "guides": { "title": "ConsoleHelpResponseGuides", "type": "object", "properties": { "device": { "type": "string" }, "server": { "type": "string" } }, "required": [ "device", "server" ], "additionalProperties": true } }, "required": [ "version", "deployment_id", "docs_url", "guides" ], "additionalProperties": true }, "example": { "version": "2026.09.04", "deployment_id": "deployment-01", "docs_url": "https://cisco-open.github.io/intelligent-release-image-staging/docs/", "guides": { "device": "/help-device.html", "server": "/help-server.html" } } } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/swarmmap": { "get": { "operationId": "console_get_swarmmap", "summary": "Open swarm map", "description": "Open swarm map. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Authenticated HTML application", "content": { "text/html": { "schema": { "type": "string" }, "example": "..." } } }, "400": { "description": "Invalid Content-Length or Request body not supported or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required", "x-iris-problem-codes": [ "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Management API unavailable or Service unavailable", "x-iris-problem-codes": [ "management-api-unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management API unavailable", "status": 503, "code": "management-api-unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/healthz": { "get": { "operationId": "console_get_healthz", "summary": "Read console health", "description": "Read console health. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "none", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" }, { "url": "https://iris.example:9101", "description": "TLS telemetry listener" } ], "security": [], "parameters": [], "responses": { "200": { "description": "Non-disclosing probe result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "example": { "ok": true } } } } }, "x-iris-services": [ "console", "telemetry" ], "x-iris-service-responses": { "console": { "ok": true }, "telemetry": { "ok": true } } } }, "/readyz": { "get": { "operationId": "console_get_readyz", "summary": "Read console readiness", "description": "Read console readiness. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "none", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" }, { "url": "https://iris.example:9101", "description": "TLS telemetry listener" } ], "security": [], "parameters": [], "responses": { "200": { "description": "Non-disclosing probe result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "example": { "ok": true } } } }, "503": { "description": "Not ready; probe documents deliberately use the minimal health schema", "headers": { "Retry-After": { "description": "Seconds before another readiness check", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "example": { "ok": false } } } } }, "x-iris-services": [ "console", "telemetry" ], "x-iris-service-responses": { "console": { "ok": true }, "telemetry": { "ok": true } } } }, "/internal/v1/peer-policy": { "get": { "operationId": "management_get_internal_v1_peer_policy", "summary": "Read peer policy", "description": "Read peer policy. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read peer policy response", "content": { "application/json": { "schema": { "title": "ManagementPeerPolicyResponse", "type": "object", "properties": { "schema": { "type": "integer" }, "revision": { "type": "integer" }, "degraded": { "type": "boolean" }, "fail_closed": { "type": "boolean" }, "quarantine": { "title": "ManagementPeerPolicyResponseQuarantine", "type": "object", "properties": { "reserved": { "type": "boolean" }, "description": { "type": "string" } }, "required": [ "reserved", "description" ], "additionalProperties": true }, "quarantine_assignments": { "type": "array", "items": { "type": "string" } }, "roles_supported": { "type": "boolean", "const": true }, "roles_present": { "type": "boolean" }, "roles": { "title": "ManagementPeerPolicyResponseRoles", "type": "object", "properties": { "defined": { "type": "integer" }, "restricted": { "type": "integer" }, "members": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "required": [ "defined", "restricted", "members" ], "additionalProperties": true }, "role_drift": { "title": "ManagementPeerPolicyResponseRole_Drift", "type": "object", "properties": { "count": { "type": "integer" }, "device_ids": { "type": "array", "items": { "type": "string" } }, "truncated": { "type": "boolean" } }, "required": [ "count", "device_ids", "truncated" ], "additionalProperties": true }, "outbox": { "title": "ManagementPeerPolicyResponseOutbox", "type": "object", "properties": { "unacknowledged": { "type": "integer" }, "capacity": { "type": "integer" } }, "required": [ "unacknowledged", "capacity" ], "additionalProperties": true }, "origin_qos": { "title": "ManagementPeerPolicyResponseOrigin_Qos", "type": "object", "properties": { "state": { "type": [ "string", "null" ] }, "global_option_count": { "type": "integer" }, "target_download_count": { "type": "integer" }, "applied_download_count": { "type": "integer" }, "last_reconciled_at": { "type": [ "number", "null" ] }, "last_error": { "type": [ "string", "null" ] } }, "required": [ "state", "global_option_count", "target_download_count", "applied_download_count", "last_reconciled_at", "last_error" ], "additionalProperties": true }, "fleet_rollup": { "type": "object", "properties": { "issued_revision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "applied": { "type": "object", "propertyNames": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])(?![\\s\\S])" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "description": "Agent-asserted accepted policy revisions as exact decimal string keys, mapped to inventory-device counts." }, "states": { "type": "object", "properties": { "applied": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "lkg": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "stale": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "rejected": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "tracker-only": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "pre-instructions": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "unknown": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "unavailable": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "pending": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "forbidden": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "floor_reset": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "none": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "revoked": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } }, "additionalProperties": false } }, "required": [ "issued_revision", "applied", "states" ], "additionalProperties": false }, "instruction_status": { "type": "object", "properties": { "observed_at": { "type": "number", "minimum": 0, "maximum": 9223372036854775807 }, "instr_stamp_missing": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "pointer_skew": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "issued_revision_label": { "type": [ "string", "null" ], "maxLength": 20, "pattern": "^r(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])(?![\\s\\S])" } }, "required": [ "observed_at", "instr_stamp_missing", "pointer_skew", "issued_revision_label" ], "additionalProperties": false }, "instruction_keys": { "oneOf": [ { "type": "object", "properties": { "schema": { "type": "string", "const": "iris-instruction-key-status/v1" }, "enabled": { "type": "boolean" }, "state": { "type": "string", "enum": [ "phase0", "ready", "renewal_due", "signing_refused", "keylist_missing", "invalid", "error" ] }, "certificate_days_to_expiry": { "type": [ "integer", "null" ], "minimum": -9223372036854775807, "maximum": 9223372036854775807 }, "certificate_renewal_due": { "type": "boolean" }, "signing_refused": { "type": "boolean" }, "keylist_seq": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9223372036854775807 }, "keylist_age_days": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "keylist_resign_due": { "type": "boolean" }, "roots_configured": { "type": "integer", "minimum": 0, "maximum": 2 }, "roots_attested_180d": { "type": "integer", "minimum": 0, "maximum": 2 }, "root_ceremony_overdue": { "type": "string", "enum": [ "unknown", "ok", "warn", "critical" ] }, "root_quorum_degraded": { "type": "boolean" }, "updated_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } }, "required": [ "schema", "enabled", "state", "certificate_days_to_expiry", "certificate_renewal_due", "signing_refused", "keylist_seq", "keylist_age_days", "keylist_resign_due", "roots_configured", "roots_attested_180d", "root_ceremony_overdue", "root_quorum_degraded", "updated_at" ], "additionalProperties": false }, { "type": "null" } ], "description": "Validated durable signing-custody status, or null when the status snapshot is absent, invalid, stale or unavailable." }, "enforcement": { "title": "ManagementPeerPolicyResponseEnforcement", "type": "object", "properties": { "state": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" }, "desired_ip_count": { "type": "integer" }, "conflict_count": { "type": "integer" }, "mutual_origin": { "title": "ManagementPeerPolicyResponseEnforcementMutual_Origin", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "preflight", "enforce" ] }, "newly_denied_device_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Prospective count in preflight mode only. Null means unavailable or requested enforce mode; use GET peer-policy/origin-enforcement for separately verified application evidence. Zero is a completed preflight with no newly denied devices." } }, "required": [ "mode", "newly_denied_device_count" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "mode": { "const": "enforce" } } }, "then": { "properties": { "newly_denied_device_count": { "const": null } } } } ] } }, "required": [ "state", "stale", "desired_ip_count", "conflict_count", "mutual_origin" ], "additionalProperties": true } }, "required": [ "schema", "revision", "degraded", "fail_closed", "quarantine", "quarantine_assignments", "roles_supported", "roles_present", "roles", "role_drift", "outbox", "origin_qos", "fleet_rollup", "instruction_status", "instruction_keys", "enforcement" ], "additionalProperties": true }, "example": { "schema": 1, "revision": 4, "degraded": false, "fail_closed": false, "quarantine": { "reserved": true, "description": "reserved policy value" }, "quarantine_assignments": [ "edge-02" ], "roles_supported": true, "roles_present": true, "roles": { "defined": 1, "restricted": 1, "members": { "boat": 2 } }, "role_drift": { "count": 0, "device_ids": [], "truncated": false }, "outbox": { "unacknowledged": 1, "capacity": 256 }, "origin_qos": { "state": null, "global_option_count": 0, "target_download_count": 0, "applied_download_count": 0, "last_reconciled_at": null, "last_error": null }, "fleet_rollup": { "issued_revision": 12, "applied": { "7": 1 }, "states": { "applied": 1 } }, "instruction_status": { "observed_at": 1788470400, "instr_stamp_missing": 0, "pointer_skew": 0, "issued_revision_label": "r12" }, "instruction_keys": { "schema": "iris-instruction-key-status/v1", "enabled": true, "state": "ready", "certificate_days_to_expiry": 14, "certificate_renewal_due": false, "signing_refused": false, "keylist_seq": 8, "keylist_age_days": 30, "keylist_resign_due": false, "roots_configured": 2, "roots_attested_180d": 2, "root_ceremony_overdue": "ok", "root_quorum_degraded": false, "updated_at": 1788470400 }, "enforcement": { "state": null, "stale": false, "desired_ip_count": 1, "conflict_count": 0, "mutual_origin": { "mode": "preflight", "newly_denied_device_count": null } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Device status temporarily busy or Service unavailable", "x-iris-problem-codes": [ "projection-busy", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "projection-busy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#projection-busy", "title": "Device status temporarily busy", "status": 503, "code": "projection-busy" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/peer-policy/roles": { "get": { "operationId": "management_get_internal_v1_peer_policy_roles", "summary": "List role definitions", "description": "List role definitions. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "List role definitions response", "content": { "application/json": { "schema": { "title": "ManagementPeerPolicyRolesResponse", "type": "object", "properties": { "revision": { "type": "integer" }, "degraded": { "type": "boolean" }, "fail_closed": { "type": "boolean" }, "roles": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,31}$", "not": { "enum": [ "default", "legacy", "origin", "quarantine", "seeder" ] } }, "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "restricted": { "type": "boolean" }, "origin": { "type": "boolean" }, "peers": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,31}$", "not": { "enum": [ "default", "legacy", "origin", "quarantine", "seeder" ] } }, "minItems": 1, "maxItems": 64, "uniqueItems": true, "x-iris-selfPeerRequired": true, "description": "Must contain the role's {name} path value; missing self returns 409 role_isolated." }, "nets": { "type": "array", "items": { "type": "string", "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])(?:/(?:(?=[0-9]{1,32}$(?![\\s\\S]))0*(?:[0-9]|[12][0-9]|3[0-2])|0\\.0\\.0\\.0|0\\.0\\.0\\.1|0\\.0\\.0\\.127|0\\.0\\.0\\.15|0\\.0\\.0\\.255|0\\.0\\.0\\.3|0\\.0\\.0\\.31|0\\.0\\.0\\.63|0\\.0\\.0\\.7|0\\.0\\.1\\.255|0\\.0\\.127\\.255|0\\.0\\.15\\.255|0\\.0\\.255\\.255|0\\.0\\.3\\.255|0\\.0\\.31\\.255|0\\.0\\.63\\.255|0\\.0\\.7\\.255|0\\.1\\.255\\.255|0\\.127\\.255\\.255|0\\.15\\.255\\.255|0\\.255\\.255\\.255|0\\.3\\.255\\.255|0\\.31\\.255\\.255|0\\.63\\.255\\.255|0\\.7\\.255\\.255|1\\.255\\.255\\.255|127\\.255\\.255\\.255|128\\.0\\.0\\.0|15\\.255\\.255\\.255|192\\.0\\.0\\.0|224\\.0\\.0\\.0|240\\.0\\.0\\.0|248\\.0\\.0\\.0|252\\.0\\.0\\.0|254\\.0\\.0\\.0|255\\.0\\.0\\.0|255\\.128\\.0\\.0|255\\.192\\.0\\.0|255\\.224\\.0\\.0|255\\.240\\.0\\.0|255\\.248\\.0\\.0|255\\.252\\.0\\.0|255\\.254\\.0\\.0|255\\.255\\.0\\.0|255\\.255\\.128\\.0|255\\.255\\.192\\.0|255\\.255\\.224\\.0|255\\.255\\.240\\.0|255\\.255\\.248\\.0|255\\.255\\.252\\.0|255\\.255\\.254\\.0|255\\.255\\.255\\.0|255\\.255\\.255\\.128|255\\.255\\.255\\.192|255\\.255\\.255\\.224|255\\.255\\.255\\.240|255\\.255\\.255\\.248|255\\.255\\.255\\.252|255\\.255\\.255\\.254|255\\.255\\.255\\.255|3\\.255\\.255\\.255|31\\.255\\.255\\.255|63\\.255\\.255\\.255|7\\.255\\.255\\.255))?$(?![\\s\\S])", "description": "IPv4 address, CIDR or dotted netmask/hostmask. A decimal prefix allows at most 32 digits, including leading zeroes; valid spelling is preserved." } }, "on_stale": { "type": "string", "enum": [ "keep", "defaults" ] }, "qos": { "type": "object", "properties": { "max_peers": { "type": "integer", "minimum": 1, "maximum": 1000 }, "per_peer_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "fanout": { "type": "integer", "minimum": 1, "maximum": 1000 }, "seed_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "seed_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "max_concurrent": { "type": "integer", "minimum": 1, "maximum": 1000 }, "catalog_tick_s": { "type": "integer", "minimum": 60, "maximum": 900, "multipleOf": 60 }, "telemetry_every_ticks": { "type": "integer", "minimum": 1, "maximum": 60 }, "telemetry_pause": { "type": "boolean" }, "request_peer_speed_limit_bps": { "type": "integer", "minimum": 0, "maximum": 1000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "announce_min_interval_s": { "type": "integer", "minimum": 10, "maximum": 300 }, "numwant": { "type": "integer", "minimum": 4, "maximum": 200 }, "handout_budget": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "additionalProperties": false, "description": "Replace this layer with any supported subset; an empty object clears it. Cross-field and restricted-role semantics are validated by the policy transaction." }, "qos_state": { "$ref": "#/components/schemas/TrackerQosStateMap" } } } }, "qos_state_default": { "$ref": "#/components/schemas/TrackerQosStateMap" } }, "required": [ "revision", "degraded", "fail_closed", "roles" ], "additionalProperties": true }, "example": { "revision": 4, "degraded": false, "fail_closed": false, "roles": { "boat": { "restricted": true, "peers": [ "boat" ], "origin": true } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } } } }, "/internal/v1/peer-policy/roles/export-csv": { "get": { "operationId": "management_get_internal_v1_peer_policy_roles_export_csv", "summary": "Export role definitions as CSV", "description": "Export role definitions as CSV. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. role definition batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "CSV document", "content": { "text/csv": { "schema": { "type": "string" }, "example": "role,restricted,peers,origin,nets,on_stale\nboat,true,boat;fiber,true,,keep\n" } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "x-iris-v1-resource-path-exception": "role definition batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API" } }, "/internal/v1/peer-policy/roles/import-csv": { "post": { "operationId": "management_post_internal_v1_peer_policy_roles_import_csv", "summary": "Replace role definitions from CSV", "description": "Replace role definitions from CSV. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. role definition batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "dry_run", "in": "query", "required": false, "description": "1 previews the locked candidate without persistence; 0 commits after required confirmation.", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "example": 1 }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong policy ETag. Missing: 428; stale: 412; race under the policy lock: 409. Confirmation is candidate-bound at threshold zero, including every changed QoS document.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Replace role definitions from CSV response", "content": { "application/json": { "schema": { "title": "ManagementPeerPolicyRolesImportCsvResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "candidate_revision": { "type": "integer" }, "dry_run": { "type": "boolean" }, "member_delta": { "type": "integer" }, "origin_access_lost": { "type": "integer" }, "empty_permitted_sets": { "type": "integer" }, "role_pairs_stopped": { "type": "integer" }, "qos_changed": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ] }, "roles": { "type": "integer" } }, "required": [ "ok", "revision", "candidate_revision", "dry_run", "member_delta", "origin_access_lost", "empty_permitted_sets", "role_pairs_stopped", "qos_changed", "requires_confirmation", "confirm_token", "roles" ], "additionalProperties": true }, "examples": { "confirmationRequired": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 1, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": true, "confirm_token": "candidate-bound-sha256", "roles": 2 } }, "noConfirmation": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": false, "confirm_token": null, "roles": 2 } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "409": { "description": "Operation backlog full or Revision conflict or Role in use or Role isolated or Role reserved name", "x-iris-problem-codes": [ "operation_backlog_full", "revision_conflict", "role_in_use", "role_isolated", "role_reserved_name" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "operation_backlog_full": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#operation_backlog_full", "title": "Operation backlog full", "status": 409, "code": "operation_backlog_full" } }, "revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#revision_conflict", "title": "Revision conflict", "status": 409, "code": "revision_conflict" } }, "role_in_use": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_in_use", "title": "Role in use", "status": 409, "code": "role_in_use" } }, "role_isolated": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_isolated", "title": "Role isolated", "status": 409, "code": "role_isolated" } }, "role_reserved_name": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_reserved_name", "title": "Role reserved name", "status": 409, "code": "role_reserved_name" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "422": { "description": "Invalid policy or Invalid policy request or Invalid roles csv", "x-iris-problem-codes": [ "invalid_policy", "invalid_policy_request", "invalid_roles_csv" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_policy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy", "title": "Invalid policy", "status": 422, "code": "invalid_policy" } }, "invalid_policy_request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } }, "invalid_roles_csv": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_roles_csv", "title": "Invalid roles csv", "status": 422, "code": "invalid_roles_csv" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Confirmation required or Precondition required", "x-iris-problem-codes": [ "confirmation_required", "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "confirmation_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#confirmation_required", "title": "Confirmation required", "status": 428, "code": "confirmation_required" } }, "precondition_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "x-iris-v1-resource-path-exception": "role definition batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementPeerPolicyRolesImportCsvRequest", "type": "object", "properties": { "csv": { "type": "string" }, "confirm_token": { "type": [ "string", "null" ], "writeOnly": true } }, "required": [ "csv" ], "additionalProperties": false }, "example": { "csv": "role,restricted,peers,seed_up_bps\nboat,true,boat;fiber,12500000\nfiber,true,fiber;boat,\n", "confirm_token": "candidate-bound-sha256" } } } } } }, "/internal/v1/peer-policy/roles/{name}": { "put": { "operationId": "management_put_internal_v1_peer_policy_roles_name", "summary": "Replace a role definition", "description": "Replace a role definition. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "dry_run", "in": "query", "required": false, "description": "1 previews the locked candidate without persistence; 0 commits after required confirmation.", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "example": 1 }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong policy ETag. Missing: 428; stale: 412; race under the policy lock: 409. Confirmation is candidate-bound at threshold zero, including every changed QoS document.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Replace a role definition response", "content": { "application/json": { "schema": { "title": "ManagementPeerPolicyRolesNameResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "candidate_revision": { "type": "integer" }, "dry_run": { "type": "boolean" }, "member_delta": { "type": "integer" }, "origin_access_lost": { "type": "integer" }, "empty_permitted_sets": { "type": "integer" }, "role_pairs_stopped": { "type": "integer" }, "qos_changed": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ] } }, "required": [ "ok", "revision", "candidate_revision", "dry_run", "member_delta", "origin_access_lost", "empty_permitted_sets", "role_pairs_stopped", "qos_changed", "requires_confirmation", "confirm_token" ], "additionalProperties": true }, "examples": { "confirmationRequired": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 1, "qos_changed": false, "requires_confirmation": true, "confirm_token": "candidate-bound-sha256" } }, "noConfirmation": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": false, "confirm_token": null } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "409": { "description": "Operation backlog full or Revision conflict or Role isolated or Role reserved name", "x-iris-problem-codes": [ "operation_backlog_full", "revision_conflict", "role_isolated", "role_reserved_name" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "operation_backlog_full": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#operation_backlog_full", "title": "Operation backlog full", "status": 409, "code": "operation_backlog_full" } }, "revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#revision_conflict", "title": "Revision conflict", "status": 409, "code": "revision_conflict" } }, "role_isolated": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_isolated", "title": "Role isolated", "status": 409, "code": "role_isolated" } }, "role_reserved_name": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_reserved_name", "title": "Role reserved name", "status": 409, "code": "role_reserved_name" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "422": { "description": "Invalid policy or Invalid policy request", "x-iris-problem-codes": [ "invalid_policy", "invalid_policy_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_policy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy", "title": "Invalid policy", "status": 422, "code": "invalid_policy" } }, "invalid_policy_request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Confirmation required or Precondition required", "x-iris-problem-codes": [ "confirmation_required", "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "confirmation_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#confirmation_required", "title": "Confirmation required", "status": 428, "code": "confirmation_required" } }, "precondition_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementPeerPolicyRolesNameRequest", "type": "object", "properties": { "restricted": { "type": "boolean" }, "peers": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,31}$", "not": { "enum": [ "default", "legacy", "origin", "quarantine", "seeder" ] } }, "minItems": 1, "maxItems": 64, "uniqueItems": true, "x-iris-selfPeerRequired": true, "description": "Must contain the role's {name} path value; missing self returns 409 role_isolated." }, "origin": { "type": "boolean" }, "nets": { "type": "array", "items": { "type": "string", "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])(?:/(?:(?=[0-9]{1,32}$(?![\\s\\S]))0*(?:[0-9]|[12][0-9]|3[0-2])|0\\.0\\.0\\.0|0\\.0\\.0\\.1|0\\.0\\.0\\.127|0\\.0\\.0\\.15|0\\.0\\.0\\.255|0\\.0\\.0\\.3|0\\.0\\.0\\.31|0\\.0\\.0\\.63|0\\.0\\.0\\.7|0\\.0\\.1\\.255|0\\.0\\.127\\.255|0\\.0\\.15\\.255|0\\.0\\.255\\.255|0\\.0\\.3\\.255|0\\.0\\.31\\.255|0\\.0\\.63\\.255|0\\.0\\.7\\.255|0\\.1\\.255\\.255|0\\.127\\.255\\.255|0\\.15\\.255\\.255|0\\.255\\.255\\.255|0\\.3\\.255\\.255|0\\.31\\.255\\.255|0\\.63\\.255\\.255|0\\.7\\.255\\.255|1\\.255\\.255\\.255|127\\.255\\.255\\.255|128\\.0\\.0\\.0|15\\.255\\.255\\.255|192\\.0\\.0\\.0|224\\.0\\.0\\.0|240\\.0\\.0\\.0|248\\.0\\.0\\.0|252\\.0\\.0\\.0|254\\.0\\.0\\.0|255\\.0\\.0\\.0|255\\.128\\.0\\.0|255\\.192\\.0\\.0|255\\.224\\.0\\.0|255\\.240\\.0\\.0|255\\.248\\.0\\.0|255\\.252\\.0\\.0|255\\.254\\.0\\.0|255\\.255\\.0\\.0|255\\.255\\.128\\.0|255\\.255\\.192\\.0|255\\.255\\.224\\.0|255\\.255\\.240\\.0|255\\.255\\.248\\.0|255\\.255\\.252\\.0|255\\.255\\.254\\.0|255\\.255\\.255\\.0|255\\.255\\.255\\.128|255\\.255\\.255\\.192|255\\.255\\.255\\.224|255\\.255\\.255\\.240|255\\.255\\.255\\.248|255\\.255\\.255\\.252|255\\.255\\.255\\.254|255\\.255\\.255\\.255|3\\.255\\.255\\.255|31\\.255\\.255\\.255|63\\.255\\.255\\.255|7\\.255\\.255\\.255))?$(?![\\s\\S])", "description": "IPv4 address, CIDR or dotted netmask/hostmask. A decimal prefix allows at most 32 digits, including leading zeroes; valid spelling is preserved." } }, "on_stale": { "type": "string", "enum": [ "keep", "defaults" ] }, "qos": { "type": "object", "properties": { "max_peers": { "type": "integer", "minimum": 1, "maximum": 1000 }, "per_peer_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "fanout": { "type": "integer", "minimum": 1, "maximum": 1000 }, "seed_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "seed_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "max_concurrent": { "type": "integer", "minimum": 1, "maximum": 1000 }, "catalog_tick_s": { "type": "integer", "minimum": 60, "maximum": 900, "multipleOf": 60 }, "telemetry_every_ticks": { "type": "integer", "minimum": 1, "maximum": 60 }, "telemetry_pause": { "type": "boolean" }, "request_peer_speed_limit_bps": { "type": "integer", "minimum": 0, "maximum": 1000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "announce_min_interval_s": { "type": "integer", "minimum": 10, "maximum": 300 }, "numwant": { "type": "integer", "minimum": 4, "maximum": 200 }, "handout_budget": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "additionalProperties": false, "description": "Replace this layer with any supported subset; an empty object clears it. Cross-field and restricted-role semantics are validated by the policy transaction." }, "confirm_token": { "type": [ "string", "null" ], "writeOnly": true }, "qos_state": { "$ref": "#/components/schemas/TrackerQosStateMap" } }, "required": [], "additionalProperties": false }, "example": { "restricted": true, "peers": [ "boat" ], "origin": true, "nets": [], "on_stale": "keep", "qos": {}, "confirm_token": "candidate-bound-sha256" } } } } }, "delete": { "operationId": "management_delete_internal_v1_peer_policy_roles_name", "summary": "Delete a role definition", "description": "Delete a role definition. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "dry_run", "in": "query", "required": false, "description": "1 previews the locked candidate without persistence; 0 commits after required confirmation.", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "example": 1 }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong policy ETag. Missing: 428; stale: 412; race under the policy lock: 409. Confirmation is candidate-bound at threshold zero, including every changed QoS document.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Dry-run candidate and confirmation preview", "content": { "application/json": { "schema": { "title": "ManagementPeerPolicyRolesNameResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "candidate_revision": { "type": "integer" }, "dry_run": { "type": "boolean" }, "member_delta": { "type": "integer" }, "origin_access_lost": { "type": "integer" }, "empty_permitted_sets": { "type": "integer" }, "role_pairs_stopped": { "type": "integer" }, "qos_changed": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ] } }, "required": [ "ok", "revision", "candidate_revision", "dry_run", "member_delta", "origin_access_lost", "empty_permitted_sets", "role_pairs_stopped", "qos_changed", "requires_confirmation", "confirm_token" ], "additionalProperties": true }, "examples": { "confirmationRequired": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 1, "qos_changed": false, "requires_confirmation": true, "confirm_token": "candidate-bound-sha256" } }, "noConfirmation": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": false, "confirm_token": null } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "204": { "description": "Role deleted; no body", "headers": { "ETag": { "schema": { "type": "string" } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Role not found or Route not found", "x-iris-problem-codes": [ "role_not_found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "role_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found", "title": "Role not found", "status": 404, "code": "role_not_found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "409": { "description": "Operation backlog full or Revision conflict or Role in use or Role reserved name", "x-iris-problem-codes": [ "operation_backlog_full", "revision_conflict", "role_in_use", "role_reserved_name" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "operation_backlog_full": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#operation_backlog_full", "title": "Operation backlog full", "status": 409, "code": "operation_backlog_full" } }, "revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#revision_conflict", "title": "Revision conflict", "status": 409, "code": "revision_conflict" } }, "role_in_use": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_in_use", "title": "Role in use", "status": 409, "code": "role_in_use" } }, "role_reserved_name": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_reserved_name", "title": "Role reserved name", "status": 409, "code": "role_reserved_name" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "422": { "description": "Invalid policy or Invalid policy request", "x-iris-problem-codes": [ "invalid_policy", "invalid_policy_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_policy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy", "title": "Invalid policy", "status": 422, "code": "invalid_policy" } }, "invalid_policy_request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Confirmation required or Precondition required", "x-iris-problem-codes": [ "confirmation_required", "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "confirmation_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#confirmation_required", "title": "Confirmation required", "status": 428, "code": "confirmation_required" } }, "precondition_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm_token": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "example": { "confirm_token": "candidate-bound-sha256" } } } } } }, "/internal/v1/peer-policy/qos": { "put": { "operationId": "management_put_internal_v1_peer_policy_qos", "summary": "Replace global or role QoS", "description": "Replace global or role QoS. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "dry_run", "in": "query", "required": false, "description": "1 previews the locked candidate without persistence; 0 commits after required confirmation.", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "example": 1 }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong policy ETag. Missing: 428; stale: 412; race under the policy lock: 409. Confirmation is candidate-bound at threshold zero, including every changed QoS document.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Replace global or role QoS response", "content": { "application/json": { "schema": { "title": "ManagementPeerPolicyQosResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "candidate_revision": { "type": "integer" }, "dry_run": { "type": "boolean" }, "member_delta": { "type": "integer" }, "origin_access_lost": { "type": "integer" }, "empty_permitted_sets": { "type": "integer" }, "role_pairs_stopped": { "type": "integer" }, "qos_changed": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ] } }, "required": [ "ok", "revision", "candidate_revision", "dry_run", "member_delta", "origin_access_lost", "empty_permitted_sets", "role_pairs_stopped", "qos_changed", "requires_confirmation", "confirm_token" ], "additionalProperties": true }, "examples": { "confirmationRequired": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": true, "requires_confirmation": true, "confirm_token": "candidate-bound-sha256" } }, "noConfirmation": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": false, "confirm_token": null } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Role not found or Route not found", "x-iris-problem-codes": [ "role_not_found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "role_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found", "title": "Role not found", "status": 404, "code": "role_not_found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "409": { "description": "Operation backlog full or Revision conflict or Role reserved name", "x-iris-problem-codes": [ "operation_backlog_full", "revision_conflict", "role_reserved_name" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "operation_backlog_full": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#operation_backlog_full", "title": "Operation backlog full", "status": 409, "code": "operation_backlog_full" } }, "revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#revision_conflict", "title": "Revision conflict", "status": 409, "code": "revision_conflict" } }, "role_reserved_name": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_reserved_name", "title": "Role reserved name", "status": 409, "code": "role_reserved_name" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "422": { "description": "Invalid policy or Invalid policy request", "x-iris-problem-codes": [ "invalid_policy", "invalid_policy_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_policy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy", "title": "Invalid policy", "status": 422, "code": "invalid_policy" } }, "invalid_policy_request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Confirmation required or Precondition required", "x-iris-problem-codes": [ "confirmation_required", "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "confirmation_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#confirmation_required", "title": "Confirmation required", "status": 428, "code": "confirmation_required" } }, "precondition_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementPeerPolicyQosRequest", "type": "object", "properties": { "qos": { "type": "object", "properties": { "max_peers": { "type": "integer", "minimum": 1, "maximum": 1000 }, "per_peer_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "fanout": { "type": "integer", "minimum": 1, "maximum": 1000 }, "seed_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "seed_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "max_concurrent": { "type": "integer", "minimum": 1, "maximum": 1000 }, "catalog_tick_s": { "type": "integer", "minimum": 60, "maximum": 900, "multipleOf": 60 }, "telemetry_every_ticks": { "type": "integer", "minimum": 1, "maximum": 60 }, "telemetry_pause": { "type": "boolean" }, "request_peer_speed_limit_bps": { "type": "integer", "minimum": 0, "maximum": 1000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "announce_min_interval_s": { "type": "integer", "minimum": 10, "maximum": 300 }, "numwant": { "type": "integer", "minimum": 4, "maximum": 200 }, "handout_budget": { "type": "integer", "minimum": 0, "maximum": 1000 }, "on_stale": { "type": "string", "enum": [ "keep", "defaults" ] }, "origin_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "origin_per_torrent_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "origin_max_peers": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "additionalProperties": false, "description": "Replace this layer with any supported subset; an empty object clears it. Cross-field and restricted-role semantics are validated by the policy transaction." }, "qos_state": { "$ref": "#/components/schemas/TrackerQosStateMap" }, "role": { "type": [ "string", "null" ] }, "confirm_token": { "type": [ "string", "null" ], "writeOnly": true } }, "required": [], "additionalProperties": false, "anyOf": [ { "required": [ "qos" ] }, { "required": [ "qos_state" ] } ], "description": "Global qos_state is stored at roles.qos_state_default. Role qos_state is stored at roles.defs..qos_state. Omission preserves either stored layer; an explicit empty object clears the supplied layer.", "allOf": [ { "if": { "required": [ "role" ], "properties": { "role": { "type": "string" } } }, "then": { "properties": { "qos": { "type": "object", "properties": { "max_peers": { "type": "integer", "minimum": 1, "maximum": 1000 }, "per_peer_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "fanout": { "type": "integer", "minimum": 1, "maximum": 1000 }, "seed_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "seed_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "leech_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_up_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "overall_down_bps": { "type": "integer", "minimum": 0, "maximum": 10000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "max_concurrent": { "type": "integer", "minimum": 1, "maximum": 1000 }, "catalog_tick_s": { "type": "integer", "minimum": 60, "maximum": 900, "multipleOf": 60 }, "telemetry_every_ticks": { "type": "integer", "minimum": 1, "maximum": 60 }, "telemetry_pause": { "type": "boolean" }, "request_peer_speed_limit_bps": { "type": "integer", "minimum": 0, "maximum": 1000000000, "anyOf": [ { "const": 0 }, { "minimum": 8192 } ] }, "announce_min_interval_s": { "type": "integer", "minimum": 10, "maximum": 300 }, "numwant": { "type": "integer", "minimum": 4, "maximum": 200 }, "handout_budget": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "additionalProperties": false, "description": "Replace this layer with any supported subset; an empty object clears it. Cross-field and restricted-role semantics are validated by the policy transaction." } } } } ] }, "example": { "qos": { "numwant": 25 }, "qos_state": { "seeder": { "announce_min_interval_s": 120, "numwant": 4 } }, "role": "boat", "confirm_token": "candidate-bound-sha256" } } } } } }, "/internal/v1/peer-policy/origin-enforcement": { "get": { "operationId": "management_get_internal_v1_peer_policy_origin_enforcement", "summary": "Read reviewed distribution restrictions", "description": "Read reviewed distribution restrictions. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Reviewed approval or count-only application evidence", "headers": { "ETag": { "schema": { "type": "string", "pattern": "^\"origin-enforcement-[0-9]+\"$" }, "example": "\"origin-enforcement-0\"" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0 }, "policy_revision": { "type": "integer", "minimum": 0 }, "approved_ip_count": { "type": "integer", "minimum": 0 }, "approved_device_count": { "type": "integer", "minimum": 0 }, "new_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "new_device_count": { "type": [ "integer", "null" ], "minimum": 0 }, "retained_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "proposed_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "proposed_device_count": { "type": [ "integer", "null" ], "minimum": 0 }, "shared_conflict_count": { "type": [ "integer", "null" ], "minimum": 0 }, "protected_conflict_count": { "type": [ "integer", "null" ], "minimum": 0 }, "applied_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "applied_device_count": { "type": [ "integer", "null" ], "minimum": 0 }, "mode": { "enum": [ "preflight", "enforce" ] }, "state": { "enum": [ "degraded", "enforced", "pending", "preflight", "review_required", "unavailable" ] }, "max_new_ips": { "type": "integer", "minimum": 0, "maximum": 1000 }, "max_new_devices": { "type": "integer", "minimum": 0, "maximum": 1000 }, "reason": { "enum": [ null, "application_pending", "application_state_unavailable", "apply_failed", "aria_unavailable", "control_state_unavailable", "device_budget_exceeded", "endpoint_set_changed", "endpoint_state_unavailable", "ip_budget_exceeded", "origin_mismatch", "origin_unknown", "origin_unobserved", "policy_changed", "policy_unavailable", "protected_address", "retention_capacity_exceeded", "session_changed", "shared_address" ] }, "last_verified_at": { "type": [ "number", "null" ], "minimum": 0 }, "blockers": { "type": "array", "maxItems": 18, "items": { "enum": [ "application_pending", "application_state_unavailable", "apply_failed", "aria_unavailable", "control_state_unavailable", "device_budget_exceeded", "endpoint_set_changed", "endpoint_state_unavailable", "ip_budget_exceeded", "origin_mismatch", "origin_unknown", "origin_unobserved", "policy_changed", "policy_unavailable", "protected_address", "retention_capacity_exceeded", "session_changed", "shared_address" ] } } }, "required": [ "revision", "policy_revision", "approved_ip_count", "approved_device_count", "new_ip_count", "new_device_count", "retained_ip_count", "proposed_ip_count", "proposed_device_count", "shared_conflict_count", "protected_conflict_count", "applied_ip_count", "applied_device_count", "mode", "state", "max_new_ips", "max_new_devices", "reason", "last_verified_at", "blockers" ], "additionalProperties": false, "description": "Count-only distribution-access approval and application evidence. Mode is requested intent; state is separately verified tracker evidence. A saved approval is pending, never immediate proof of enforcement. Null counts mean unavailable. No addresses or private application journal are exposed.", "allOf": [ { "if": { "properties": { "state": { "const": "enforced" } } }, "then": { "properties": { "mode": { "const": "enforce" }, "reason": { "const": null }, "blockers": { "maxItems": 0 }, "applied_ip_count": { "type": "integer", "minimum": 0 }, "applied_device_count": { "type": "integer", "minimum": 0 }, "last_verified_at": { "type": "number", "exclusiveMinimum": 0 } } } } ] }, "example": { "revision": 0, "policy_revision": 4, "mode": "preflight", "max_new_ips": 10, "max_new_devices": 10, "approved_ip_count": 0, "approved_device_count": 0, "new_ip_count": 2, "new_device_count": 3, "retained_ip_count": 0, "proposed_ip_count": 2, "proposed_device_count": 3, "shared_conflict_count": 0, "protected_conflict_count": 0, "state": "preflight", "reason": null, "applied_ip_count": null, "applied_device_count": null, "last_verified_at": null, "blockers": [] } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Origin enforcement unavailable or Service unavailable", "x-iris-problem-codes": [ "origin_enforcement_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "origin_enforcement_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#origin_enforcement_unavailable", "title": "Origin enforcement unavailable", "status": 503, "code": "origin_enforcement_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } } }, "put": { "operationId": "management_put_internal_v1_peer_policy_origin_enforcement", "summary": "Review or apply distribution restrictions", "description": "Review or apply distribution restrictions. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong control ETag from GET distribution access; distinct from the policy revision in the body. Required for both preview and commit. Missing: 428; malformed, weak or stale: 412.", "schema": { "type": "string", "pattern": "^\"origin-enforcement-[0-9]+\"$" }, "example": "\"origin-enforcement-0\"" } ], "responses": { "200": { "description": "Reviewed approval or count-only application evidence", "headers": { "ETag": { "schema": { "type": "string", "pattern": "^\"origin-enforcement-[0-9]+\"$" }, "example": "\"origin-enforcement-0\"" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0 }, "policy_revision": { "type": "integer", "minimum": 0 }, "approved_ip_count": { "type": "integer", "minimum": 0 }, "approved_device_count": { "type": "integer", "minimum": 0 }, "new_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "new_device_count": { "type": [ "integer", "null" ], "minimum": 0 }, "retained_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "proposed_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "proposed_device_count": { "type": [ "integer", "null" ], "minimum": 0 }, "shared_conflict_count": { "type": [ "integer", "null" ], "minimum": 0 }, "protected_conflict_count": { "type": [ "integer", "null" ], "minimum": 0 }, "applied_ip_count": { "type": [ "integer", "null" ], "minimum": 0 }, "applied_device_count": { "type": [ "integer", "null" ], "minimum": 0 }, "mode": { "enum": [ "preflight", "enforce" ] }, "state": { "enum": [ "degraded", "enforced", "pending", "preflight", "review_required", "unavailable" ] }, "max_new_ips": { "type": "integer", "minimum": 0, "maximum": 1000 }, "max_new_devices": { "type": "integer", "minimum": 0, "maximum": 1000 }, "reason": { "enum": [ null, "application_pending", "application_state_unavailable", "apply_failed", "aria_unavailable", "control_state_unavailable", "device_budget_exceeded", "endpoint_set_changed", "endpoint_state_unavailable", "ip_budget_exceeded", "origin_mismatch", "origin_unknown", "origin_unobserved", "policy_changed", "policy_unavailable", "protected_address", "retention_capacity_exceeded", "session_changed", "shared_address" ] }, "last_verified_at": { "type": [ "number", "null" ], "minimum": 0 }, "blockers": { "type": "array", "maxItems": 18, "items": { "enum": [ "application_pending", "application_state_unavailable", "apply_failed", "aria_unavailable", "control_state_unavailable", "device_budget_exceeded", "endpoint_set_changed", "endpoint_state_unavailable", "ip_budget_exceeded", "origin_mismatch", "origin_unknown", "origin_unobserved", "policy_changed", "policy_unavailable", "protected_address", "retention_capacity_exceeded", "session_changed", "shared_address" ] } }, "dry_run": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" } }, "required": [ "revision", "policy_revision", "approved_ip_count", "approved_device_count", "new_ip_count", "new_device_count", "retained_ip_count", "proposed_ip_count", "proposed_device_count", "shared_conflict_count", "protected_conflict_count", "applied_ip_count", "applied_device_count", "mode", "state", "max_new_ips", "max_new_devices", "reason", "last_verified_at", "blockers", "dry_run", "requires_confirmation", "confirm_token" ], "additionalProperties": false, "description": "Count-only distribution-access approval and application evidence. Mode is requested intent; state is separately verified tracker evidence. A saved approval is pending, never immediate proof of enforcement. Null counts mean unavailable. No addresses or private application journal are exposed.", "allOf": [ { "if": { "properties": { "dry_run": { "const": false } } }, "then": { "properties": { "requires_confirmation": { "const": false }, "confirm_token": { "const": null }, "state": { "const": "pending" }, "applied_ip_count": { "const": null }, "applied_device_count": { "const": null }, "last_verified_at": { "const": null } } }, "else": { "properties": { "requires_confirmation": { "const": true } } } } ] }, "examples": { "preview": { "value": { "revision": 0, "policy_revision": 4, "mode": "enforce", "max_new_ips": 10, "max_new_devices": 10, "approved_ip_count": 0, "approved_device_count": 0, "new_ip_count": 2, "new_device_count": 3, "retained_ip_count": 0, "proposed_ip_count": 2, "proposed_device_count": 3, "shared_conflict_count": 0, "protected_conflict_count": 0, "state": "preflight", "reason": null, "applied_ip_count": null, "applied_device_count": null, "last_verified_at": null, "blockers": [], "dry_run": true, "requires_confirmation": true, "confirm_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "blocked": { "value": { "revision": 0, "policy_revision": 4, "mode": "enforce", "max_new_ips": 10, "max_new_devices": 10, "approved_ip_count": 0, "approved_device_count": 0, "new_ip_count": 2, "new_device_count": 3, "retained_ip_count": 0, "proposed_ip_count": 2, "proposed_device_count": 3, "shared_conflict_count": 1, "protected_conflict_count": 0, "state": "preflight", "reason": null, "applied_ip_count": null, "applied_device_count": null, "last_verified_at": null, "blockers": [ "shared_address" ], "dry_run": true, "requires_confirmation": true, "confirm_token": null } }, "accepted": { "value": { "revision": 1, "policy_revision": 4, "mode": "enforce", "max_new_ips": 10, "max_new_devices": 10, "approved_ip_count": 2, "approved_device_count": 3, "new_ip_count": 2, "new_device_count": 3, "retained_ip_count": 0, "proposed_ip_count": 2, "proposed_device_count": 3, "shared_conflict_count": 0, "protected_conflict_count": 0, "state": "pending", "reason": null, "applied_ip_count": null, "applied_device_count": null, "last_verified_at": null, "blockers": [], "dry_run": false, "requires_confirmation": false, "confirm_token": null } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "409": { "description": "Origin enforcement blocked or Origin review stale or Policy revision conflict", "x-iris-problem-codes": [ "origin_enforcement_blocked", "origin_review_stale", "policy_revision_conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "origin_enforcement_blocked": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#origin_enforcement_blocked", "title": "Origin enforcement blocked", "status": 409, "code": "origin_enforcement_blocked" } }, "origin_review_stale": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#origin_review_stale", "title": "Origin review stale", "status": 409, "code": "origin_review_stale" } }, "policy_revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_revision_conflict", "title": "Policy revision conflict", "status": 409, "code": "policy_revision_conflict" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "422": { "description": "Invalid origin enforcement", "x-iris-problem-codes": [ "invalid_origin_enforcement" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_origin_enforcement", "title": "Invalid origin enforcement", "status": 422, "code": "invalid_origin_enforcement" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Precondition required", "x-iris-problem-codes": [ "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Origin enforcement unavailable or Service unavailable", "x-iris-problem-codes": [ "origin_enforcement_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "origin_enforcement_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#origin_enforcement_unavailable", "title": "Origin enforcement unavailable", "status": 503, "code": "origin_enforcement_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "enum": [ "preflight", "enforce" ] }, "max_new_ips": { "type": "integer", "minimum": 0, "maximum": 1000 }, "max_new_devices": { "type": "integer", "minimum": 0, "maximum": 1000 }, "if_policy_revision": { "type": "integer", "minimum": 0 }, "dry_run": { "type": "boolean" }, "confirm_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "mode", "max_new_ips", "max_new_devices", "if_policy_revision", "dry_run" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "dry_run": { "const": false } } }, "then": { "required": [ "confirm_token" ] } } ], "description": "Preview with dry_run=true using the current control ETag and policy revision. Commit the exact same mode, limits and revisions with dry_run=false and the returned confirmation token. Both enabling and disabling require a preview bound to the exact reviewed policy, origin and peer bindings. A changed peer set requires a new preview even if counts are unchanged." }, "example": { "mode": "enforce", "max_new_ips": 10, "max_new_devices": 10, "if_policy_revision": 4, "dry_run": true } } } } } }, "/internal/v1/devices/{device_id}/role": { "post": { "operationId": "management_post_internal_v1_devices_device_id_role", "summary": "Set a device role", "description": "Set a device role. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "dry_run", "in": "query", "required": false, "description": "1 previews the locked candidate without persistence; 0 commits after required confirmation.", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "example": 1 }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong policy ETag. Missing: 428; stale: 412; race under the policy lock: 409. Confirmation is candidate-bound at threshold zero, including every changed QoS document.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Set a device role response", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdRoleResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "candidate_revision": { "type": "integer" }, "dry_run": { "type": "boolean" }, "member_delta": { "type": "integer" }, "origin_access_lost": { "type": "integer" }, "empty_permitted_sets": { "type": "integer" }, "role_pairs_stopped": { "type": "integer" }, "qos_changed": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ] }, "partial": { "type": "boolean" }, "applied": { "type": "integer" }, "failed": { "title": "ManagementDevicesDeviceIdRoleResponseFailed", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "direction": { "type": "string" }, "role_drift": { "title": "ManagementDevicesDeviceIdRoleResponseRole_Drift", "type": "object", "properties": { "count": { "type": "integer" }, "device_ids": { "type": "array", "items": { "type": "string" } }, "truncated": { "type": "boolean" } }, "required": [ "count", "device_ids", "truncated" ], "additionalProperties": true } }, "required": [ "ok", "revision", "dry_run", "partial", "applied", "failed", "direction", "role_drift" ], "additionalProperties": true }, "examples": { "confirmationRequired": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 1, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": true, "confirm_token": "candidate-bound-sha256", "partial": false, "applied": 1, "failed": {}, "direction": "tighten", "role_drift": { "count": 0, "device_ids": [], "truncated": false } } }, "noConfirmation": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": false, "confirm_token": null, "partial": false, "applied": 1, "failed": {}, "direction": "tighten", "role_drift": { "count": 0, "device_ids": [], "truncated": false } } }, "unchangedMembership": { "value": { "ok": true, "revision": 5, "dry_run": false, "partial": false, "applied": 1, "failed": {}, "direction": "neutral", "role_drift": { "count": 0, "device_ids": [], "truncated": false } } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Device not found or Role not found or Route not found", "x-iris-problem-codes": [ "device_not_found", "role_not_found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "device_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#device_not_found", "title": "Device not found", "status": 404, "code": "device_not_found" } }, "role_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found", "title": "Role not found", "status": 404, "code": "role_not_found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "409": { "description": "Operation backlog full or Revision conflict or Role reserved name or Role shadowed by assignment", "x-iris-problem-codes": [ "operation_backlog_full", "revision_conflict", "role_reserved_name", "role_shadowed_by_assignment" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "operation_backlog_full": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#operation_backlog_full", "title": "Operation backlog full", "status": 409, "code": "operation_backlog_full" } }, "revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#revision_conflict", "title": "Revision conflict", "status": 409, "code": "revision_conflict" } }, "role_reserved_name": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_reserved_name", "title": "Role reserved name", "status": 409, "code": "role_reserved_name" } }, "role_shadowed_by_assignment": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_shadowed_by_assignment", "title": "Role shadowed by assignment", "status": 409, "code": "role_shadowed_by_assignment" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Bad role or Incomparable role change or Invalid policy or Invalid policy request", "x-iris-problem-codes": [ "bad_role", "incomparable_role_change", "invalid_policy", "invalid_policy_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_role": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#bad_role", "title": "Bad role", "status": 422, "code": "bad_role" } }, "incomparable_role_change": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#incomparable_role_change", "title": "Incomparable role change", "status": 422, "code": "incomparable_role_change" } }, "invalid_policy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy", "title": "Invalid policy", "status": 422, "code": "invalid_policy" } }, "invalid_policy_request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Confirmation required or Precondition required", "x-iris-problem-codes": [ "confirmation_required", "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "confirmation_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#confirmation_required", "title": "Confirmation required", "status": 428, "code": "confirmation_required" } }, "precondition_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Fleet write failed or Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "fleet_write_failed", "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "fleet_write_failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#fleet_write_failed", "title": "Fleet write failed", "status": 503, "code": "fleet_write_failed" } }, "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdRoleRequest", "type": "object", "properties": { "role": { "type": [ "string", "null" ] }, "confirm_token": { "type": [ "string", "null" ], "writeOnly": true } }, "required": [ "role" ], "additionalProperties": false }, "example": { "role": "boat", "confirm_token": "candidate-bound-sha256" } } } } } }, "/internal/v1/devices/bulk-role": { "post": { "operationId": "management_post_internal_v1_devices_bulk_role", "summary": "Set device roles in bulk", "description": "Set device roles in bulk. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. fleet batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "dry_run", "in": "query", "required": false, "description": "1 previews the locked candidate without persistence; 0 commits after required confirmation.", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "example": 1 }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong policy ETag. Missing: 428; stale: 412; race under the policy lock: 409. Confirmation is candidate-bound at threshold zero, including every changed QoS document.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Set device roles in bulk response", "content": { "application/json": { "schema": { "title": "ManagementDevicesBulkRoleResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "candidate_revision": { "type": "integer" }, "dry_run": { "type": "boolean" }, "member_delta": { "type": "integer" }, "origin_access_lost": { "type": "integer" }, "empty_permitted_sets": { "type": "integer" }, "role_pairs_stopped": { "type": "integer" }, "qos_changed": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ] }, "partial": { "type": "boolean" }, "applied": { "type": "integer" }, "failed": { "title": "ManagementDevicesBulkRoleResponseFailed", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "direction": { "type": "string" }, "role_drift": { "title": "ManagementDevicesBulkRoleResponseRole_Drift", "type": "object", "properties": { "count": { "type": "integer" }, "device_ids": { "type": "array", "items": { "type": "string" } }, "truncated": { "type": "boolean" } }, "required": [ "count", "device_ids", "truncated" ], "additionalProperties": true } }, "required": [ "ok", "revision", "dry_run", "partial", "applied", "failed", "direction", "role_drift" ], "additionalProperties": true }, "examples": { "confirmationRequired": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 1, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": true, "confirm_token": "candidate-bound-sha256", "partial": false, "applied": 2, "failed": {}, "direction": "tighten", "role_drift": { "count": 0, "device_ids": [], "truncated": false } } }, "noConfirmation": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": false, "confirm_token": null, "partial": false, "applied": 2, "failed": {}, "direction": "tighten", "role_drift": { "count": 0, "device_ids": [], "truncated": false } } }, "unchangedMembership": { "value": { "ok": true, "revision": 5, "dry_run": false, "partial": false, "applied": 2, "failed": {}, "direction": "neutral", "role_drift": { "count": 0, "device_ids": [], "truncated": false } } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Role not found or Route not found", "x-iris-problem-codes": [ "role_not_found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "role_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found", "title": "Role not found", "status": 404, "code": "role_not_found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "409": { "description": "Operation backlog full or Revision conflict or Role reserved name or Role shadowed by assignment", "x-iris-problem-codes": [ "operation_backlog_full", "revision_conflict", "role_reserved_name", "role_shadowed_by_assignment" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "operation_backlog_full": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#operation_backlog_full", "title": "Operation backlog full", "status": 409, "code": "operation_backlog_full" } }, "revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#revision_conflict", "title": "Revision conflict", "status": 409, "code": "revision_conflict" } }, "role_reserved_name": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_reserved_name", "title": "Role reserved name", "status": 409, "code": "role_reserved_name" } }, "role_shadowed_by_assignment": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_shadowed_by_assignment", "title": "Role shadowed by assignment", "status": 409, "code": "role_shadowed_by_assignment" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Bad role or Incomparable role change or Invalid policy or Invalid policy request or Mixed role direction", "x-iris-problem-codes": [ "bad_role", "incomparable_role_change", "invalid_policy", "invalid_policy_request", "mixed_role_direction" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_role": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#bad_role", "title": "Bad role", "status": 422, "code": "bad_role" } }, "incomparable_role_change": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#incomparable_role_change", "title": "Incomparable role change", "status": 422, "code": "incomparable_role_change" } }, "invalid_policy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy", "title": "Invalid policy", "status": 422, "code": "invalid_policy" } }, "invalid_policy_request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } }, "mixed_role_direction": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#mixed_role_direction", "title": "Mixed role direction", "status": 422, "code": "mixed_role_direction" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Confirmation required or Precondition required", "x-iris-problem-codes": [ "confirmation_required", "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "confirmation_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#confirmation_required", "title": "Confirmation required", "status": 428, "code": "confirmation_required" } }, "precondition_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Fleet write failed or Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "fleet_write_failed", "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "fleet_write_failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#fleet_write_failed", "title": "Fleet write failed", "status": 503, "code": "fleet_write_failed" } }, "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "x-iris-v1-resource-path-exception": "fleet batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementDevicesBulkRoleRequest", "type": "object", "properties": { "device_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 10000 }, "role": { "type": [ "string", "null" ] }, "confirm_token": { "type": [ "string", "null" ], "writeOnly": true } }, "required": [ "device_ids", "role" ], "additionalProperties": false }, "example": { "device_ids": [ "edge-01", "edge-02" ], "role": "boat", "confirm_token": "candidate-bound-sha256" } } } } } }, "/internal/v1/devices/{device_id}/effective-qos": { "get": { "operationId": "management_get_internal_v1_devices_device_id_effective_qos", "summary": "Explain effective device QoS", "description": "Explain effective device QoS. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "tracker_state", "in": "query", "required": false, "description": "Selects the seeder or leecher tracker cadence explanation. Omission preserves the v1 scalar-only response bytes.", "schema": { "type": "string", "enum": [ "seeder", "leecher" ] }, "example": "seeder" } ], "responses": { "200": { "description": "Explain effective device QoS response", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdEffectiveQosResponse", "type": "object", "properties": { "revision": { "type": "integer" }, "degraded": { "type": "boolean" }, "fail_closed": { "type": "boolean" }, "device_id": { "type": "string" }, "delivery_state": { "type": "string", "const": "pre-instructions", "deprecated": true, "description": "Legacy Phase 0 compatibility sentinel. Always pre-instructions; use instruction for current delivery and application status." }, "qos": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQos", "type": "object", "properties": { "max_peers": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosMax_Peers", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "per_peer_bps": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosPer_Peer_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "fanout": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosFanout", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "seed_up_bps": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosSeed_Up_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" }, "derived_from": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosSeed_Up_BpsDerived_From", "type": "object", "properties": { "per_peer_bps": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosSeed_Up_BpsDerived_FromPer_Peer_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "fanout": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosSeed_Up_BpsDerived_FromFanout", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true } }, "required": [ "per_peer_bps", "fanout" ], "additionalProperties": true } }, "required": [ "value", "source" ], "additionalProperties": true }, "seed_down_bps": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosSeed_Down_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" }, "derived_from": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosSeed_Down_BpsDerived_From", "type": "object", "properties": { "per_peer_bps": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosSeed_Down_BpsDerived_FromPer_Peer_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "fanout": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosSeed_Down_BpsDerived_FromFanout", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true } }, "required": [ "per_peer_bps", "fanout" ], "additionalProperties": true } }, "required": [ "value", "source" ], "additionalProperties": true }, "leech_up_bps": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosLeech_Up_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" }, "derived_from": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosLeech_Up_BpsDerived_From", "type": "object", "properties": { "per_peer_bps": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosLeech_Up_BpsDerived_FromPer_Peer_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "fanout": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosLeech_Up_BpsDerived_FromFanout", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true } }, "required": [ "per_peer_bps", "fanout" ], "additionalProperties": true } }, "required": [ "value", "source" ], "additionalProperties": true }, "leech_down_bps": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosLeech_Down_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" }, "derived_from": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosLeech_Down_BpsDerived_From", "type": "object", "properties": { "per_peer_bps": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosLeech_Down_BpsDerived_FromPer_Peer_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "fanout": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosLeech_Down_BpsDerived_FromFanout", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true } }, "required": [ "per_peer_bps", "fanout" ], "additionalProperties": true } }, "required": [ "value", "source" ], "additionalProperties": true }, "overall_up_bps": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosOverall_Up_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "overall_down_bps": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosOverall_Down_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "max_concurrent": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosMax_Concurrent", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "request_peer_speed_limit_bps": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosRequest_Peer_Speed_Limit_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "announce_min_interval_s": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosAnnounce_Min_Interval_S", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "numwant": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosNumwant", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" }, "effective_ceiling": { "type": "integer" }, "runtime_request_zero": { "type": "string" }, "constraint_source": { "type": "string" } }, "required": [ "value", "source", "effective_ceiling", "runtime_request_zero", "constraint_source" ], "additionalProperties": true }, "handout_budget": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosHandout_Budget", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "catalog_tick_s": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosCatalog_Tick_S", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" }, "offline_horizon_s": { "type": "integer" }, "heartbeat_always": { "type": "boolean" } }, "required": [ "value", "source", "offline_horizon_s", "heartbeat_always" ], "additionalProperties": true }, "telemetry_every_ticks": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosTelemetry_Every_Ticks", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "peer_telemetry_interval_s": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosPeer_Telemetry_Interval_S", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "telemetry_pause": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosTelemetry_Pause", "type": "object", "properties": { "value": { "type": "boolean" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "on_stale": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosOn_Stale", "type": "object", "properties": { "value": { "type": "string" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "origin_up_bps": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosOrigin_Up_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "origin_per_torrent_up_bps": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosOrigin_Per_Torrent_Up_Bps", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true }, "origin_max_peers": { "title": "ManagementDevicesDeviceIdEffectiveQosResponseQosOrigin_Max_Peers", "type": "object", "properties": { "value": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "value", "source" ], "additionalProperties": true } }, "required": [ "max_peers", "per_peer_bps", "fanout", "seed_up_bps", "seed_down_bps", "leech_up_bps", "leech_down_bps", "overall_up_bps", "overall_down_bps", "max_concurrent", "request_peer_speed_limit_bps", "announce_min_interval_s", "numwant", "handout_budget", "catalog_tick_s", "telemetry_every_ticks", "peer_telemetry_interval_s", "telemetry_pause", "on_stale", "origin_up_bps", "origin_per_torrent_up_bps", "origin_max_peers" ], "additionalProperties": true }, "instruction": { "type": "object", "properties": { "display_state": { "type": "string", "enum": [ "applied", "lkg", "stale", "rejected", "tracker-only", "pre-instructions", "unknown", "unavailable", "pending", "forbidden", "floor_reset", "none", "revoked" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 96 }, "evidence": { "type": "string", "enum": [ "agent-asserted", "server-observed" ] }, "underlying_state": { "type": [ "string", "null" ], "enum": [ "allowlist_expired", "applied", "audience_mismatch", "floor_reset", "instr_forbidden", "instr_pending", "instr_unavailable", "key_rejected", "lkg", "lkg_rejected", "lkg_unreadable", "none", "oversize", "reasserted", "rollback_rejected", "stale_expired", "tamper_rejected", "tracker-only", "verifier_missing", null ] }, "underlying_label": { "type": "string", "minLength": 1, "maxLength": 96 }, "underlying_evidence": { "type": "string", "const": "agent-asserted" }, "reason": { "type": [ "string", "null" ], "enum": [ "bad_mac", "unknown_key", null ] }, "reported_instr_serial": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "accepted_identity": { "oneOf": [ { "type": "object", "required": [ "epoch", "instr_serial", "policy_revision" ], "additionalProperties": false, "properties": { "epoch": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "instr_serial": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "policy_revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } } }, { "type": "null" } ], "description": "Complete accepted-envelope identity asserted by the agent. Null means no complete accepted identity was reported." }, "verify_level": { "type": [ "string", "null" ], "enum": [ "sig", "none", null ] }, "pointer_skew": { "type": [ "boolean", "null" ] }, "qos_drift_count": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 49 }, "report_age_seconds": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "report_stale": { "type": [ "boolean", "null" ] }, "revoked": { "type": [ "boolean", "null" ] }, "revocation_evidence": { "type": "string", "const": "server-observed" } }, "required": [ "display_state", "label", "evidence", "underlying_state", "underlying_label", "underlying_evidence", "reason", "reported_instr_serial", "accepted_identity", "verify_level", "pointer_skew", "qos_drift_count", "report_age_seconds", "report_stale", "revoked", "revocation_evidence" ], "additionalProperties": false, "description": "Canonical bounded instruction display projection. Device facts remain assertions; server-observed revocation and report age may take display precedence while retaining the underlying report." }, "tracker_state": { "type": "string", "enum": [ "seeder", "leecher" ] }, "tracker_qos": { "type": "object", "additionalProperties": false, "properties": { "announce_min_interval_s": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": "integer", "minimum": 10, "maximum": 300 }, "source": { "type": "string", "pattern": "^(?:builtin|global|global-state:(?:seeder|leecher)|role:[a-z0-9][a-z0-9._-]{0,31}|role-state:[a-z0-9][a-z0-9._-]{0,31}:(?:seeder|leecher))$" } }, "required": [ "value", "source" ] }, "numwant": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": "integer", "minimum": 4, "maximum": 200 }, "source": { "type": "string", "pattern": "^(?:builtin|global|global-state:(?:seeder|leecher)|role:[a-z0-9][a-z0-9._-]{0,31}|role-state:[a-z0-9][a-z0-9._-]{0,31}:(?:seeder|leecher))$" }, "effective_ceiling": { "type": "integer", "minimum": 4, "maximum": 50 }, "runtime_request_zero": { "type": "string", "const": "disabled" }, "constraint_source": { "type": "string", "const": "pinned-aria2-client" } }, "required": [ "value", "source", "effective_ceiling", "runtime_request_zero", "constraint_source" ] } }, "required": [ "announce_min_interval_s", "numwant" ] } }, "required": [ "revision", "degraded", "fail_closed", "device_id", "delivery_state", "qos", "instruction" ], "additionalProperties": true, "dependentRequired": { "tracker_state": [ "tracker_qos" ], "tracker_qos": [ "tracker_state" ] } }, "example": { "revision": 4, "degraded": false, "fail_closed": false, "device_id": "edge-01", "delivery_state": "pre-instructions", "qos": { "max_peers": { "value": 10, "source": "builtin" }, "per_peer_bps": { "value": 20000, "source": "global" }, "fanout": { "value": 1, "source": "builtin" }, "seed_up_bps": { "value": 20000, "source": "global", "derived_from": { "per_peer_bps": { "value": 20000, "source": "global" }, "fanout": { "value": 1, "source": "builtin" } } }, "seed_down_bps": { "value": 20000, "source": "global", "derived_from": { "per_peer_bps": { "value": 20000, "source": "global" }, "fanout": { "value": 1, "source": "builtin" } } }, "leech_up_bps": { "value": 20000, "source": "global", "derived_from": { "per_peer_bps": { "value": 20000, "source": "global" }, "fanout": { "value": 1, "source": "builtin" } } }, "leech_down_bps": { "value": 20000, "source": "global", "derived_from": { "per_peer_bps": { "value": 20000, "source": "global" }, "fanout": { "value": 1, "source": "builtin" } } }, "overall_up_bps": { "value": 0, "source": "builtin" }, "overall_down_bps": { "value": 0, "source": "builtin" }, "max_concurrent": { "value": 100, "source": "builtin" }, "request_peer_speed_limit_bps": { "value": 51200, "source": "builtin" }, "announce_min_interval_s": { "value": 30, "source": "builtin" }, "numwant": { "value": 50, "source": "builtin", "effective_ceiling": 50, "runtime_request_zero": "disabled", "constraint_source": "pinned-aria2-client" }, "handout_budget": { "value": 0, "source": "builtin" }, "catalog_tick_s": { "value": 60, "source": "builtin", "offline_horizon_s": 600, "heartbeat_always": true }, "telemetry_every_ticks": { "value": 1, "source": "builtin" }, "peer_telemetry_interval_s": { "value": 60, "source": "builtin" }, "telemetry_pause": { "value": false, "source": "builtin" }, "on_stale": { "value": "defaults", "source": "builtin" }, "origin_up_bps": { "value": 0, "source": "builtin" }, "origin_per_torrent_up_bps": { "value": 0, "source": "builtin" }, "origin_max_peers": { "value": 55, "source": "builtin" } }, "instruction": { "display_state": "applied", "label": "applied r9223372036854775807", "evidence": "agent-asserted", "underlying_state": "applied", "underlying_label": "applied r9223372036854775807", "underlying_evidence": "agent-asserted", "reason": null, "reported_instr_serial": 9223372036854775807, "accepted_identity": { "epoch": 11, "instr_serial": 9223372036854775807, "policy_revision": 7 }, "verify_level": "sig", "pointer_skew": false, "qos_drift_count": 0, "report_age_seconds": 3, "report_stale": false, "revoked": false, "revocation_evidence": "server-observed" }, "tracker_state": "seeder", "tracker_qos": { "announce_min_interval_s": { "value": 120, "source": "role-state:boat:seeder" }, "numwant": { "value": 4, "source": "global-state:seeder", "effective_ceiling": 4, "runtime_request_zero": "disabled", "constraint_source": "pinned-aria2-client" } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Device not found or Route not found", "x-iris-problem-codes": [ "device_not_found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "device_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#device_not_found", "title": "Device not found", "status": 404, "code": "device_not_found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "422": { "description": "Invalid policy request", "x-iris-problem-codes": [ "invalid_policy_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API" } }, "/internal/v1/peer-policy/explain": { "get": { "operationId": "management_get_internal_v1_peer_policy_explain", "summary": "Explain mutual peer access", "description": "Explain mutual peer access. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "a", "in": "query", "required": true, "description": "Bare device ID, device:, or service:seeder. Requires one fresh, unambiguous durable IPv4 attribution; no inventory-IP fallback.", "schema": { "type": "string" }, "example": "edge-01" }, { "name": "b", "in": "query", "required": true, "description": "Bare device ID, device:, or service:seeder. Requires one fresh, unambiguous durable IPv4 attribution; no inventory-IP fallback.", "schema": { "type": "string" }, "example": "service:seeder" } ], "responses": { "200": { "description": "Explain mutual peer access response", "content": { "application/json": { "schema": { "title": "ManagementPeerPolicyExplainResponse", "type": "object", "properties": { "revision": { "type": "integer" }, "degraded": { "type": "boolean" }, "fail_closed": { "type": "boolean" }, "a": { "title": "ManagementPeerPolicyExplainResponseA", "type": "object", "properties": { "principal": { "title": "ManagementPeerPolicyExplainResponseAPrincipal", "type": "object", "properties": { "type": { "type": "string", "enum": [ "device", "service" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": true }, "role": { "type": [ "string", "null" ] }, "acl_source": { "type": "string" }, "acl_name": { "type": [ "string", "null" ] }, "decision": { "type": "string" }, "matched_seq": { "type": [ "integer", "null" ] }, "role_unknown": { "type": "boolean" }, "role_shadowed_by": { "type": [ "string", "null" ] } }, "required": [ "principal", "role", "acl_source", "acl_name", "decision", "matched_seq", "role_unknown", "role_shadowed_by" ], "additionalProperties": true }, "b": { "title": "ManagementPeerPolicyExplainResponseB", "type": "object", "properties": { "principal": { "title": "ManagementPeerPolicyExplainResponseBPrincipal", "type": "object", "properties": { "type": { "type": "string", "enum": [ "device", "service" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": true }, "role": { "type": [ "string", "null" ] }, "acl_source": { "type": "string" }, "acl_name": { "type": [ "string", "null" ] }, "decision": { "type": "string" }, "matched_seq": { "type": [ "integer", "null" ] }, "role_unknown": { "type": "boolean" }, "role_shadowed_by": { "type": [ "string", "null" ] } }, "required": [ "principal", "role", "acl_source", "acl_name", "decision", "matched_seq", "role_unknown", "role_shadowed_by" ], "additionalProperties": true }, "mutual": { "type": "boolean" } }, "required": [ "revision", "degraded", "fail_closed", "a", "b", "mutual" ], "additionalProperties": true }, "example": { "revision": 4, "degraded": false, "fail_closed": false, "a": { "principal": { "type": "device", "id": "edge-01" }, "role": "boat", "acl_source": "role:boat", "acl_name": "role:boat", "decision": "permit", "matched_seq": 10, "role_unknown": false, "role_shadowed_by": null }, "b": { "principal": { "type": "device", "id": "edge-02" }, "role": "boat", "acl_source": "role:boat", "acl_name": "role:boat", "decision": "permit", "matched_seq": 10, "role_unknown": false, "role_shadowed_by": null }, "mutual": true } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "422": { "description": "Principal unresolvable", "x-iris-problem-codes": [ "principal_unresolvable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#principal_unresolvable", "title": "Principal unresolvable", "status": 422, "code": "principal_unresolvable" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } } } }, "/internal/v1/peer-policy/quarantine/{device_id}": { "put": { "operationId": "management_put_internal_v1_peer_policy_quarantine_device_id", "summary": "Set device quarantine", "description": "Set device quarantine. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": false, "description": "Strong ETag from GET peer-policy. Body if_revision remains until the advertised Sunset for v1 clients.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Set device quarantine response", "content": { "application/json": { "schema": { "title": "ManagementPeerPolicyQuarantineDeviceIdResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "quarantined": { "type": "boolean" } }, "required": [ "ok", "revision", "quarantined" ], "additionalProperties": true }, "example": { "ok": true, "revision": 5, "quarantined": true } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-5\"" } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition-failed", "title": "Precondition failed", "status": 412, "code": "precondition-failed" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Unprocessable content", "x-iris-problem-codes": [ "unprocessable-content" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#unprocessable-content", "title": "Unprocessable content", "status": 422, "code": "unprocessable-content" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-compatibility": "Body if_revision is retained through 2027-09-04; omission emits Deprecation and Sunset.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementPeerPolicyQuarantineDeviceIdRequest", "type": "object", "properties": { "quarantined": { "type": "boolean" }, "if_revision": { "type": "integer" } }, "required": [ "quarantined", "if_revision" ], "additionalProperties": true }, "example": { "quarantined": true, "if_revision": 4 } } } } } }, "/internal/v1/audit": { "get": { "operationId": "management_get_internal_v1_audit", "summary": "List audit events", "description": "List audit events. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque next_cursor from the previous page. Keep time/category filters unchanged. A 409 requires a fresh first page.", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "example": 200 }, { "name": "before_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788470400 }, { "name": "after_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788384000 }, { "name": "category", "in": "query", "required": false, "description": "Audit event category", "schema": { "type": "string" }, "example": "auth" } ], "responses": { "200": { "description": "List audit events response", "content": { "application/json": { "schema": { "title": "ManagementAuditResponse", "type": "object", "properties": { "events": { "type": "array", "items": { "title": "ManagementAuditResponseEventsItem", "type": "object", "properties": { "ts": { "type": "integer" }, "event": { "type": "string" }, "category": { "type": "string" }, "result": { "type": "string" } }, "required": [ "ts", "event", "result" ], "additionalProperties": true } }, "next_cursor": { "type": [ "string", "null" ], "maxLength": 256 } }, "required": [ "events", "next_cursor" ], "additionalProperties": true }, "example": { "events": [ { "ts": 1788470400, "event": "login", "category": "auth", "result": "ok" } ], "next_cursor": null } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/audit/histogram": { "get": { "operationId": "management_get_internal_v1_audit_histogram", "summary": "Read audit histogram", "description": "Read audit histogram. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "example": "auth" }, { "name": "buckets", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "example": 30 }, { "name": "window", "in": "query", "required": false, "description": "Seconds ending at server now; ignored when both bounds are present", "schema": { "type": "number", "exclusiveMinimum": 0 }, "example": 604800 }, { "name": "since_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788384000 }, { "name": "until_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788470400 } ], "responses": { "200": { "description": "Read audit histogram response", "content": { "application/json": { "schema": { "title": "ManagementAuditHistogramResponse", "type": "object", "properties": { "buckets": { "type": "array", "items": { "title": "ManagementAuditHistogramResponseBucketsItem", "type": "object", "properties": { "start": { "type": "integer" }, "count": { "type": "integer" } }, "required": [ "start", "count" ], "additionalProperties": true } }, "now": { "type": "integer" }, "bucket_seconds": { "type": "integer" } }, "required": [ "buckets", "now", "bucket_seconds" ], "additionalProperties": true }, "example": { "buckets": [ { "start": 1788470400, "count": 1 } ], "now": 1788474000, "bucket_seconds": 120 } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/session": { "get": { "operationId": "management_get_internal_v1_session", "summary": "Read console session", "description": "Read console session. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read console session response", "content": { "application/json": { "schema": { "title": "ManagementSessionResponse", "type": "object", "properties": { "username": { "type": "string" }, "csrf": { "type": "string" } }, "required": [ "username", "csrf" ], "additionalProperties": true }, "example": { "username": "admin", "csrf": "session-csrf-token" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/settings/key-maintenance": { "get": { "operationId": "management_get_internal_v1_settings_key_maintenance", "summary": "Read key maintenance policies and operations", "description": "Read key maintenance policies and operations. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read key maintenance policies and operations response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "const": 1 }, "revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "observed_at": { "type": [ "integer", "null" ] }, "worker": { "enum": [ "not-observed", "observed", "stale", "clock-error" ] }, "policies": { "type": "array", "maxItems": 32, "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "family": { "enum": [ "online-signer", "device-instruction", "management-token", "browser-tls", "management-tls", "device-tls", "peer-ca", "offline-roots", "age-identity", "seeder-token", "metrics-token", "collector-headers" ] }, "target": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "next_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "interval_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "window_minutes": { "type": "integer", "minimum": 5, "maximum": 1440 } }, "required": [ "id", "family", "target", "enabled", "next_at", "interval_days", "window_minutes" ], "additionalProperties": false } }, "jobs": { "type": "array", "maxItems": 256, "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "policy_id": { "type": "string", "format": "uuid" }, "family": { "enum": [ "online-signer", "device-instruction", "management-token", "browser-tls", "management-tls", "device-tls", "peer-ca", "offline-roots", "age-identity", "seeder-token", "metrics-token", "collector-headers" ] }, "target": { "type": "string" }, "state": { "enum": [ "approval-required", "cancelled", "completed", "intervention-required", "missed", "review-required", "reviewed", "running", "verification-required" ] }, "due_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "updated_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "detail": { "type": "string", "maxLength": 300 }, "before": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "after": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" } }, "required": [ "id", "policy_id", "family", "target", "state", "due_at", "updated_at", "detail", "before", "after" ], "additionalProperties": false } }, "families": { "type": "array", "items": { "type": "object", "properties": { "id": { "enum": [ "online-signer", "device-instruction", "management-token", "browser-tls", "management-tls", "device-tls", "peer-ca", "offline-roots", "age-identity", "seeder-token", "metrics-token", "collector-headers" ] }, "label": { "type": "string" }, "action": { "enum": [ "prepare", "rotate", "review" ] }, "requirement": { "type": "string" }, "guide": { "type": "string" } }, "required": [ "id", "label", "action", "requirement", "guide" ], "additionalProperties": false } }, "peer_leaf_renewal": { "type": "string" } }, "required": [ "schema", "revision", "observed_at", "worker", "policies", "jobs", "families", "peer_leaf_renewal" ], "additionalProperties": false }, "example": { "schema": 1, "revision": 0, "policies": [], "jobs": [], "observed_at": null, "worker": "not-observed", "families": [ { "id": "online-signer", "label": "Online instruction signer", "action": "prepare", "requirement": "Offline certificate and retirement approvals", "guide": "admin-guide/signer-rotation/" }, { "id": "device-instruction", "label": "Device instruction encryption key", "action": "rotate", "requirement": "Seven-day overlap; verify device acceptance", "guide": "admin-guide/rotations/#rotate-one-devices-instruction-key" }, { "id": "management-token", "label": "Console management credential", "action": "rotate", "requirement": "Verify all Console instances before retiring overlap", "guide": "admin-guide/rotations/#rotate-the-management-credential" }, { "id": "browser-tls", "label": "Console browser TLS", "action": "review", "requirement": "Public request, approval and listener verification in Certificates & keys", "guide": "admin-guide/console-credentials/#replace-the-browser-certificate" }, { "id": "management-tls", "label": "Management TLS", "action": "review", "requirement": "Stage Console trust, replace server pair, verify listeners", "guide": "admin-guide/rotations/#rotate-the-management-certificate" }, { "id": "device-tls", "label": "Device-pinned TLS", "action": "review", "requirement": "Device trust rollout and re-onboarding", "guide": "admin-guide/rotations/#rotate-the-certificate-that-devices-trust" }, { "id": "peer-ca", "label": "Private swarm issuing CA", "action": "review", "requirement": "Coordinated trust rollout; distinct from automatic leaf renewal", "guide": "admin-guide/rotations/" }, { "id": "offline-roots", "label": "Offline signing roots", "action": "review", "requirement": "Independent custodians and device trust rollout", "guide": "admin-guide/instruction-keys/" }, { "id": "age-identity", "label": "Encryption-at-rest identity and recipients", "action": "review", "requirement": "Protected backup, stopped writers and decryption proof", "guide": "admin-guide/rotations/#rotate-the-age-recipients" }, { "id": "seeder-token", "label": "Seeder announce credential", "action": "review", "requirement": "Maintenance freeze and tracker serving proof", "guide": "admin-guide/rotations/#rotate-the-seeder-announce-credential" }, { "id": "metrics-token", "label": "Metrics scrape credential", "action": "review", "requirement": "Console replacement, scraper migration and verified retirement", "guide": "admin-guide/console-credentials/#replace-the-metrics-scraping-token" }, { "id": "collector-headers", "label": "Outbound telemetry credentials", "action": "review", "requirement": "Console replacement, collector approval and delivery proof", "guide": "admin-guide/console-credentials/#replace-outbound-collector-authentication" } ], "peer_leaf_renewal": "Device-managed; one-day certificates renew six hours before expiry." } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "management_post_internal_v1_settings_key_maintenance", "summary": "Configure or approve key maintenance", "description": "Configure or approve key maintenance. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Configure or approve key maintenance response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "const": 1 }, "revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "observed_at": { "type": [ "integer", "null" ] }, "worker": { "enum": [ "not-observed", "observed", "stale", "clock-error" ] }, "policies": { "type": "array", "maxItems": 32, "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "family": { "enum": [ "online-signer", "device-instruction", "management-token", "browser-tls", "management-tls", "device-tls", "peer-ca", "offline-roots", "age-identity", "seeder-token", "metrics-token", "collector-headers" ] }, "target": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "next_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "interval_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "window_minutes": { "type": "integer", "minimum": 5, "maximum": 1440 } }, "required": [ "id", "family", "target", "enabled", "next_at", "interval_days", "window_minutes" ], "additionalProperties": false } }, "jobs": { "type": "array", "maxItems": 256, "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "policy_id": { "type": "string", "format": "uuid" }, "family": { "enum": [ "online-signer", "device-instruction", "management-token", "browser-tls", "management-tls", "device-tls", "peer-ca", "offline-roots", "age-identity", "seeder-token", "metrics-token", "collector-headers" ] }, "target": { "type": "string" }, "state": { "enum": [ "approval-required", "cancelled", "completed", "intervention-required", "missed", "review-required", "reviewed", "running", "verification-required" ] }, "due_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "updated_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "detail": { "type": "string", "maxLength": 300 }, "before": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "after": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" } }, "required": [ "id", "policy_id", "family", "target", "state", "due_at", "updated_at", "detail", "before", "after" ], "additionalProperties": false } }, "families": { "type": "array", "items": { "type": "object", "properties": { "id": { "enum": [ "online-signer", "device-instruction", "management-token", "browser-tls", "management-tls", "device-tls", "peer-ca", "offline-roots", "age-identity", "seeder-token", "metrics-token", "collector-headers" ] }, "label": { "type": "string" }, "action": { "enum": [ "prepare", "rotate", "review" ] }, "requirement": { "type": "string" }, "guide": { "type": "string" } }, "required": [ "id", "label", "action", "requirement", "guide" ], "additionalProperties": false } }, "peer_leaf_renewal": { "type": "string" } }, "required": [ "schema", "revision", "observed_at", "worker", "policies", "jobs", "families", "peer_leaf_renewal" ], "additionalProperties": false }, "example": { "schema": 1, "revision": 0, "policies": [], "jobs": [], "observed_at": null, "worker": "not-observed", "families": [ { "id": "online-signer", "label": "Online instruction signer", "action": "prepare", "requirement": "Offline certificate and retirement approvals", "guide": "admin-guide/signer-rotation/" }, { "id": "device-instruction", "label": "Device instruction encryption key", "action": "rotate", "requirement": "Seven-day overlap; verify device acceptance", "guide": "admin-guide/rotations/#rotate-one-devices-instruction-key" }, { "id": "management-token", "label": "Console management credential", "action": "rotate", "requirement": "Verify all Console instances before retiring overlap", "guide": "admin-guide/rotations/#rotate-the-management-credential" }, { "id": "browser-tls", "label": "Console browser TLS", "action": "review", "requirement": "Public request, approval and listener verification in Certificates & keys", "guide": "admin-guide/console-credentials/#replace-the-browser-certificate" }, { "id": "management-tls", "label": "Management TLS", "action": "review", "requirement": "Stage Console trust, replace server pair, verify listeners", "guide": "admin-guide/rotations/#rotate-the-management-certificate" }, { "id": "device-tls", "label": "Device-pinned TLS", "action": "review", "requirement": "Device trust rollout and re-onboarding", "guide": "admin-guide/rotations/#rotate-the-certificate-that-devices-trust" }, { "id": "peer-ca", "label": "Private swarm issuing CA", "action": "review", "requirement": "Coordinated trust rollout; distinct from automatic leaf renewal", "guide": "admin-guide/rotations/" }, { "id": "offline-roots", "label": "Offline signing roots", "action": "review", "requirement": "Independent custodians and device trust rollout", "guide": "admin-guide/instruction-keys/" }, { "id": "age-identity", "label": "Encryption-at-rest identity and recipients", "action": "review", "requirement": "Protected backup, stopped writers and decryption proof", "guide": "admin-guide/rotations/#rotate-the-age-recipients" }, { "id": "seeder-token", "label": "Seeder announce credential", "action": "review", "requirement": "Maintenance freeze and tracker serving proof", "guide": "admin-guide/rotations/#rotate-the-seeder-announce-credential" }, { "id": "metrics-token", "label": "Metrics scrape credential", "action": "review", "requirement": "Console replacement, scraper migration and verified retirement", "guide": "admin-guide/console-credentials/#replace-the-metrics-scraping-token" }, { "id": "collector-headers", "label": "Outbound telemetry credentials", "action": "review", "requirement": "Console replacement, collector approval and delivery proof", "guide": "admin-guide/console-credentials/#replace-outbound-collector-authentication" } ], "peer_leaf_renewal": "Device-managed; one-day certificates renew six hours before expiry." } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "const": "save-policy" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "policy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "family": { "enum": [ "online-signer", "device-instruction", "management-token", "browser-tls", "management-tls", "device-tls", "peer-ca", "offline-roots", "age-identity", "seeder-token", "metrics-token", "collector-headers" ] }, "target": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "next_at": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "interval_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "window_minutes": { "type": "integer", "minimum": 5, "maximum": 1440 } }, "required": [ "id", "family", "target", "enabled", "next_at", "interval_days", "window_minutes" ], "additionalProperties": false } }, "required": [ "action", "revision", "policy" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "enum": [ "retry", "reviewed", "retire-management", "reconcile-management" ] }, "job_id": { "type": "string", "format": "uuid" }, "confirm": { "const": true } }, "required": [ "action", "job_id", "confirm" ], "additionalProperties": false } ] }, "example": { "action": "save-policy", "revision": 0, "policy": { "id": "00000000-0000-0000-0000-000000000001", "family": "online-signer", "target": "deployment", "enabled": false, "next_at": 1790294400, "interval_days": 14, "window_minutes": 30 } } } } } } }, "/internal/v1/login": { "post": { "operationId": "management_post_internal_v1_login", "summary": "Create console session", "description": "Create console session. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consolePassword", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consolePassword": [] } ], "parameters": [], "responses": { "200": { "description": "Session credentials, or a one-use setup grant before the first administrator exists", "headers": { "Set-Cookie": { "description": "Present only for a configured administrator login", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "ManagementLoginSession", "type": "object", "properties": { "username": { "type": "string" }, "csrf": { "type": "string" } }, "required": [ "username", "csrf" ], "additionalProperties": false }, { "title": "ManagementLoginSetupGrant", "type": "object", "properties": { "setup": { "type": "boolean" }, "setup_grant": { "type": "string" } }, "required": [ "setup", "setup_grant" ], "additionalProperties": false } ] }, "examples": { "configured": { "value": { "username": "admin", "csrf": "session-csrf-token" } }, "firstRun": { "value": { "setup": true, "setup_grant": "short-lived-one-time-grant" } } } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Authentication required", "x-iris-problem-codes": [ "management-authentication-required", "authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#authentication-required", "title": "Authentication required", "status": 401, "code": "authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementLoginRequest", "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string", "format": "password", "writeOnly": true } }, "required": [ "username", "password" ], "additionalProperties": false }, "example": { "username": "admin", "password": "operator-entered-password" } } } } } }, "/internal/v1/setup": { "post": { "operationId": "management_post_internal_v1_setup", "summary": "Create the first administrator", "description": "Create the first administrator. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+setupGrant", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "setupGrant": [] } ], "parameters": [], "responses": { "200": { "description": "Create the first administrator response", "content": { "application/json": { "schema": { "title": "ManagementSetupResponse", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required", "x-iris-problem-codes": [ "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "Forbidden", "x-iris-problem-codes": [ "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "415": { "description": "Unsupported media type", "x-iris-problem-codes": [ "unsupported-media-type" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#unsupported-media-type", "title": "Unsupported media type", "status": 415, "code": "unsupported-media-type" } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementSetupRequest", "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string", "format": "password", "writeOnly": true }, "setup_grant": { "type": "string", "writeOnly": true } }, "required": [ "username", "password", "setup_grant" ], "additionalProperties": false }, "example": { "username": "admin", "password": "new-administrator-password", "setup_grant": "short-lived-one-time-grant" } } } } } }, "/internal/v1/logout": { "post": { "operationId": "management_post_internal_v1_logout", "summary": "End console session", "description": "End console session. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "End console session response", "content": { "application/json": { "schema": { "title": "ManagementLogoutResponse", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementLogoutRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/internal/v1/images": { "get": { "operationId": "management_get_internal_v1_images", "summary": "List images", "description": "List images. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. This bounded v1 collection has no pagination parameter; adding one without a stable compatibility shape is deferred to the next major version.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "List images response", "content": { "application/json": { "schema": { "title": "ManagementImagesResponse", "type": "object", "properties": { "images": { "type": "array", "items": { "title": "ManagementImagesResponseImagesItem", "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer" }, "sha256": { "type": "string" } }, "required": [ "id", "filename", "size", "sha256" ], "additionalProperties": true } } }, "required": [ "images" ], "additionalProperties": true }, "example": { "images": [ { "id": "image-01", "filename": "image.bin", "size": 1048576, "sha256": "0000000000000000000000000000000000000000000000000000000000000000" } ] } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/images/importable": { "get": { "operationId": "management_get_internal_v1_images_importable", "summary": "List importable images", "description": "List importable images. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "List importable images response", "content": { "application/json": { "schema": { "title": "ManagementImagesImportableResponse", "type": "object", "properties": { "importable": { "type": "array", "items": { "title": "ManagementImagesImportableResponseImportableItem", "type": "object", "properties": { "path": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer" } }, "required": [ "path", "filename", "size" ], "additionalProperties": true } }, "skipped": { "type": "array", "items": { "type": "string" } } }, "required": [ "importable", "skipped" ], "additionalProperties": true }, "example": { "importable": [ { "path": "/srv/images/ios-xe/image.bin", "filename": "image.bin", "size": 1048576 } ], "skipped": [] } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/images/import": { "post": { "operationId": "management_post_internal_v1_images_import", "summary": "Import an image", "description": "Import an image. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. image lifecycle action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Import an image response", "content": { "application/json": { "schema": { "title": "ManagementImagesImportResponse", "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ], "additionalProperties": true }, "example": { "job_id": "job-01" } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "image lifecycle action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementImagesImportRequest", "type": "object", "properties": { "path": { "type": "string" } }, "required": [ "path" ], "additionalProperties": true }, "example": { "path": "/srv/images/ios-xe/example.bin" } } } } } }, "/internal/v1/images/upload/{filename}": { "put": { "operationId": "management_put_internal_v1_images_upload_filename", "summary": "Upload an image", "description": "Upload an image. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "filename", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Upload an image response", "content": { "application/json": { "schema": { "title": "ManagementImagesUploadFilenameResponse", "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ], "additionalProperties": true }, "example": { "job_id": "job-01" } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "408": { "description": "Request timeout", "x-iris-problem-codes": [ "request-timeout" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-timeout", "title": "Request timeout", "status": 408, "code": "request-timeout" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": {}, "example": "" } } } } }, "/internal/v1/images/jobs/{job_id}": { "get": { "operationId": "management_get_internal_v1_images_jobs_job_id", "summary": "Read image job", "description": "Read image job. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" } ], "responses": { "200": { "description": "Current publish phase and, after the durable publish, the Cisco Bulk Hash reconciliation result", "content": { "application/json": { "schema": { "oneOf": [ { "title": "ManagementImagesJobsJobIdResponsePublishing", "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "message": { "type": "string" }, "started_at": { "type": "integer" }, "state": { "type": "string", "const": "publishing" }, "image_id": { "type": "null" }, "finished_at": { "type": "null" }, "verification": { "type": "null" } }, "required": [ "id", "state", "filename", "message", "image_id", "started_at", "finished_at", "verification" ], "additionalProperties": true }, { "title": "ManagementImagesJobsJobIdResponseVerifying", "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "message": { "type": "string" }, "started_at": { "type": "integer" }, "state": { "type": "string", "const": "verifying" }, "image_id": { "type": "string" }, "finished_at": { "type": "null" }, "verification": { "title": "ManagementImagesJobsJobIdResponseVerificationRunning", "type": "object", "properties": { "outcome": { "type": "string", "const": "running" }, "image_state": { "type": [ "string", "null" ], "enum": [ "verified", "mismatch", "not_in_feed", null ] } }, "required": [ "outcome", "image_state" ], "additionalProperties": false } }, "required": [ "id", "state", "filename", "message", "image_id", "started_at", "finished_at", "verification" ], "additionalProperties": true }, { "title": "ManagementImagesJobsJobIdResponseDone", "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "message": { "type": "string" }, "started_at": { "type": "integer" }, "state": { "type": "string", "const": "done" }, "image_id": { "type": "string" }, "finished_at": { "type": "integer" }, "verification": { "oneOf": [ { "title": "ManagementImagesJobsJobIdResponseVerificationSuccess", "type": "object", "properties": { "outcome": { "type": "string", "const": "ok" }, "image_state": { "type": [ "string", "null" ], "enum": [ "verified", "mismatch", "not_in_feed", null ] }, "matched": { "type": [ "integer", "null" ], "minimum": 0 }, "mismatched": { "type": [ "integer", "null" ], "minimum": 0 }, "not_in_feed": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "outcome", "image_state", "matched", "mismatched", "not_in_feed" ], "additionalProperties": false }, { "title": "ManagementImagesJobsJobIdResponseVerificationFailure", "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "fail", "already_running" ] }, "image_state": { "type": [ "string", "null" ], "enum": [ "verified", "mismatch", "not_in_feed", null ] }, "detail": { "type": "string" } }, "required": [ "outcome", "image_state", "detail" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "state", "filename", "message", "image_id", "started_at", "finished_at", "verification" ], "additionalProperties": true }, { "title": "ManagementImagesJobsJobIdResponseError", "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "message": { "type": "string" }, "started_at": { "type": "integer" }, "state": { "type": "string", "const": "error" }, "image_id": { "type": [ "string", "null" ] }, "finished_at": { "type": "integer" }, "verification": { "type": "null" } }, "required": [ "id", "state", "filename", "message", "image_id", "started_at", "finished_at", "verification" ], "additionalProperties": true } ] }, "examples": { "publishing": { "value": { "id": "job-01", "state": "publishing", "filename": "image.bin", "message": "", "image_id": null, "started_at": 1788470400, "finished_at": null, "verification": null } }, "verifying": { "value": { "id": "job-01", "state": "verifying", "filename": "image.bin", "message": "", "image_id": "image-01", "started_at": 1788470400, "finished_at": null, "verification": { "outcome": "running", "image_state": null } } }, "verified": { "value": { "id": "job-01", "state": "done", "filename": "image.bin", "message": "", "image_id": "image-01", "started_at": 1788470400, "finished_at": 1788470412, "verification": { "outcome": "ok", "image_state": "verified", "matched": 1, "mismatched": 0, "not_in_feed": 0 } } }, "verificationFailed": { "value": { "id": "job-01", "state": "done", "filename": "image.bin", "message": "published, but Cisco hash verification did not complete", "image_id": "image-01", "started_at": 1788470400, "finished_at": 1788470412, "verification": { "outcome": "fail", "image_state": null, "detail": "feed unavailable" } } }, "publishFailed": { "value": { "id": "job-01", "state": "error", "filename": "image.bin", "message": "publish failed", "image_id": null, "started_at": 1788470400, "finished_at": 1788470401, "verification": null } } } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/images/{image_id}": { "delete": { "operationId": "management_delete_internal_v1_images_image_id", "summary": "Delete an image", "description": "Delete an image. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "image_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Delete an image response", "content": { "application/json": { "schema": { "title": "ManagementImagesImageIdResponse", "type": "object", "properties": { "deleted": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "deleted", "warnings" ], "additionalProperties": true }, "example": { "deleted": true, "warnings": [] } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/images/{image_id}/release-quarantine": { "post": { "operationId": "management_post_internal_v1_images_image_id_release_quarantine", "summary": "Release image quarantine", "description": "Release image quarantine. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. image lifecycle action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "image_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Release image quarantine response", "content": { "application/json": { "schema": { "title": "ManagementImagesImageIdReleaseQuarantineResponse", "type": "object", "properties": { "released": { "type": "boolean" }, "override": { "type": "boolean" }, "state": { "type": "string" }, "seeding_resumed": { "type": "boolean" } }, "required": [ "released", "override", "state", "seeding_resumed" ], "additionalProperties": true }, "example": { "released": true, "override": false, "state": "verified", "seeding_resumed": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "image lifecycle action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementImagesImageIdReleaseQuarantineRequest", "type": "object", "properties": { "override": { "type": "boolean" }, "confirm_text": { "type": "string" } }, "required": [], "additionalProperties": true }, "example": { "override": false, "confirm_text": "" } } } } } }, "/internal/v1/image-verification/offline": { "post": { "operationId": "management_post_internal_v1_image_verification_offline", "summary": "Upload offline verification data", "description": "Upload offline verification data. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. verification job action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Upload offline verification data response", "content": { "application/json": { "schema": { "title": "ManagementImageVerificationOfflineResponse", "type": "object", "properties": { "outcome": { "type": "string" }, "matched": { "type": "integer" }, "mismatched": { "type": "integer" }, "not_in_feed": { "type": "integer" } }, "required": [ "outcome", "matched", "mismatched", "not_in_feed" ], "additionalProperties": true }, "example": { "outcome": "ok", "matched": 1, "mismatched": 0, "not_in_feed": 0 } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "408": { "description": "Request timeout", "x-iris-problem-codes": [ "request-timeout" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-timeout", "title": "Request timeout", "status": 408, "code": "request-timeout" } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "502": { "description": "Upstream operation failed", "x-iris-problem-codes": [ "upstream-operation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#upstream-operation-failed", "title": "Upstream operation failed", "status": 502, "code": "upstream-operation-failed" } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "verification job action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": {}, "example": "" } } } } }, "/internal/v1/image-verification/refresh": { "post": { "operationId": "management_post_internal_v1_image_verification_refresh", "summary": "Start image verification refresh", "description": "Start image verification refresh. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. verification job action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Start image verification refresh response", "content": { "application/json": { "schema": { "title": "ManagementImageVerificationRefreshResponse", "type": "object", "properties": { "outcome": { "type": "string" }, "matched": { "type": "integer" }, "mismatched": { "type": "integer" }, "not_in_feed": { "type": "integer" } }, "required": [ "outcome", "matched", "mismatched", "not_in_feed" ], "additionalProperties": true }, "example": { "outcome": "ok", "matched": 1, "mismatched": 0, "not_in_feed": 0 } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "502": { "description": "Upstream operation failed", "x-iris-problem-codes": [ "upstream-operation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#upstream-operation-failed", "title": "Upstream operation failed", "status": 502, "code": "upstream-operation-failed" } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "verification job action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementImageVerificationRefreshRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/internal/v1/devices": { "get": { "operationId": "management_get_internal_v1_devices", "summary": "List devices", "description": "List devices. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Status filter keys remain stable: deployed displays as Staged, placement-failed as Staging failed, and waiting-staging means an assigned device has not reported work on the current set. Current per-image errors take precedence over earlier staged flags.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size; omit for the v1 whole-fleet compatibility response", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "example": 100 }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset; paged results sort by device_id", "schema": { "type": "integer", "minimum": 0 }, "example": 0 }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive device search", "schema": { "type": "string" }, "example": "edge" }, { "name": "management_type", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "routed", "inband", "router-routed", "router-nat", "xr-host", "legacy" ] }, "example": "inband" }, { "name": "platform", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "guestshell", "iox", "router", "xr-appmgr", "__none" ] }, "example": "iox" }, { "name": "cred", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string" }, "example": "default" }, { "name": "telemetry", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "on", "off", "unknown" ] }, "example": "on" }, { "name": "peer", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "quarantined", "not-quarantined" ] }, "example": "not-quarantined" }, { "name": "role", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string" }, "example": "boat" }, { "name": "model_family", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "IE3x00", "IR1x00", "C9xxx", "C8xxx", "ISR/ASR/CSR", "XR8000", "NCS", "unknown" ] }, "example": "C9xxx" }, { "name": "os_family", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "xe", "xr" ] }, "example": "xe" }, { "name": "status", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "onboarding", "undeploying", "waiting-heartbeat", "waiting-staging", "onboard-failed", "undeploy-failed", "deployed", "placement-failed", "image-failed", "copying", "staging", "unassigned", "enrolled", "not-enrolled", "offline", "__attention" ] }, "example": "deployed" } ], "responses": { "200": { "description": "List devices response", "content": { "application/json": { "schema": { "title": "ManagementDevicesResponse", "type": "object", "properties": { "devices": { "type": "array", "items": { "title": "ManagementDevicesResponseDevicesItem", "type": "object", "properties": { "device_id": { "type": "string" }, "device_ip": { "type": "string" }, "model_family": { "type": "string" }, "os_family": { "type": "string" }, "platform_resolved": { "type": "string" }, "instruction": { "type": "object", "properties": { "display_state": { "type": "string", "enum": [ "applied", "lkg", "stale", "rejected", "tracker-only", "pre-instructions", "unknown", "unavailable", "pending", "forbidden", "floor_reset", "none", "revoked" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 96 }, "evidence": { "type": "string", "enum": [ "agent-asserted", "server-observed" ] }, "underlying_state": { "type": [ "string", "null" ], "enum": [ "allowlist_expired", "applied", "audience_mismatch", "floor_reset", "instr_forbidden", "instr_pending", "instr_unavailable", "key_rejected", "lkg", "lkg_rejected", "lkg_unreadable", "none", "oversize", "reasserted", "rollback_rejected", "stale_expired", "tamper_rejected", "tracker-only", "verifier_missing", null ] }, "underlying_label": { "type": "string", "minLength": 1, "maxLength": 96 }, "underlying_evidence": { "type": "string", "const": "agent-asserted" }, "reason": { "type": [ "string", "null" ], "enum": [ "bad_mac", "unknown_key", null ] }, "reported_instr_serial": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "accepted_identity": { "oneOf": [ { "type": "object", "required": [ "epoch", "instr_serial", "policy_revision" ], "additionalProperties": false, "properties": { "epoch": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "instr_serial": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "policy_revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } } }, { "type": "null" } ], "description": "Complete accepted-envelope identity asserted by the agent. Null means no complete accepted identity was reported." }, "verify_level": { "type": [ "string", "null" ], "enum": [ "sig", "none", null ] }, "pointer_skew": { "type": [ "boolean", "null" ] }, "qos_drift_count": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 49 }, "report_age_seconds": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "report_stale": { "type": [ "boolean", "null" ] }, "revoked": { "type": [ "boolean", "null" ] }, "revocation_evidence": { "type": "string", "const": "server-observed" } }, "required": [ "display_state", "label", "evidence", "underlying_state", "underlying_label", "underlying_evidence", "reason", "reported_instr_serial", "accepted_identity", "verify_level", "pointer_skew", "qos_drift_count", "report_age_seconds", "report_stale", "revoked", "revocation_evidence" ], "additionalProperties": false, "description": "Canonical bounded instruction display projection. Device facts remain assertions; server-observed revocation and report age may take display precedence while retaining the underlying report." }, "peer_tls": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "configured_mode", "runtime_mode", "runtime_source" ], "properties": { "configured_mode": { "enum": [ "disabled", "required" ] }, "runtime_mode": { "enum": [ "disabled", "required", "unknown" ] }, "runtime_source": { "enum": [ "aria2_rpc", "unknown" ] }, "revocations": { "type": "object", "properties": { "supported": { "const": true }, "mode": { "enum": [ "required", "disabled" ] }, "state": { "enum": [ "valid", "unavailable", "expired" ] }, "authority": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "issued_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "expires_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "own_revoked": { "type": "boolean" }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "supported", "mode", "state", "authority", "revision", "issued_at", "expires_at", "own_revoked", "observed_at" ], "additionalProperties": false } }, "description": "Last reported torrent TLS daemon policy, not negotiated connection evidence. Missing means unknown." }, { "type": "null" } ] } }, "required": [ "device_id", "device_ip", "model_family", "os_family", "platform_resolved", "instruction" ], "additionalProperties": true } }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "revision": { "type": "integer" }, "now": { "type": "integer" }, "target_facts": { "title": "ManagementDevicesResponseTarget_Facts", "type": "object", "properties": { "missing_os_family": { "type": "integer" }, "role_drift": { "type": "integer" } }, "required": [ "missing_os_family", "role_drift" ], "additionalProperties": true }, "target_warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "devices", "total", "offset", "limit", "revision", "now", "target_facts", "target_warnings" ], "additionalProperties": true }, "example": { "devices": [ { "device_id": "edge-01", "device_ip": "192.0.2.10", "model_family": "C9xxx", "os_family": "xe", "platform_resolved": "guestshell", "instruction": { "display_state": "applied", "label": "applied r9223372036854775807", "evidence": "agent-asserted", "underlying_state": "applied", "underlying_label": "applied r9223372036854775807", "underlying_evidence": "agent-asserted", "reason": null, "reported_instr_serial": 9223372036854775807, "accepted_identity": { "epoch": 11, "instr_serial": 9223372036854775807, "policy_revision": 7 }, "verify_level": "sig", "pointer_skew": false, "qos_drift_count": 0, "report_age_seconds": 3, "report_stale": false, "revoked": false, "revocation_evidence": "server-observed" } } ], "total": 1, "offset": 0, "limit": null, "revision": 7, "now": 1788470400, "target_facts": { "missing_os_family": 0, "role_drift": 0 }, "target_warnings": [] } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-fleet-7\"" } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Device status temporarily busy or Service unavailable", "x-iris-problem-codes": [ "projection-busy", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "projection-busy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#projection-busy", "title": "Device status temporarily busy", "status": 503, "code": "projection-busy" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "management_post_internal_v1_devices", "summary": "Create a device", "description": "Create a device. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size; omit for the v1 whole-fleet compatibility response", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "example": 100 }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset; paged results sort by device_id", "schema": { "type": "integer", "minimum": 0 }, "example": 0 }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive device search", "schema": { "type": "string" }, "example": "edge" }, { "name": "management_type", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "routed", "inband", "router-routed", "router-nat", "xr-host", "legacy" ] }, "example": "inband" }, { "name": "platform", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "guestshell", "iox", "router", "xr-appmgr", "__none" ] }, "example": "iox" }, { "name": "cred", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string" }, "example": "default" }, { "name": "telemetry", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "on", "off", "unknown" ] }, "example": "on" }, { "name": "peer", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "quarantined", "not-quarantined" ] }, "example": "not-quarantined" }, { "name": "role", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string" }, "example": "boat" }, { "name": "model_family", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "IE3x00", "IR1x00", "C9xxx", "C8xxx", "ISR/ASR/CSR", "XR8000", "NCS", "unknown" ] }, "example": "C9xxx" }, { "name": "os_family", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "xe", "xr" ] }, "example": "xe" }, { "name": "status", "in": "query", "required": false, "description": "Exact server-side device table filter", "schema": { "type": "string", "enum": [ "onboarding", "undeploying", "waiting-heartbeat", "waiting-staging", "onboard-failed", "undeploy-failed", "deployed", "placement-failed", "image-failed", "copying", "staging", "unassigned", "enrolled", "not-enrolled", "offline", "__attention" ] }, "example": "deployed" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Create a device response", "content": { "application/json": { "schema": { "title": "ManagementDevicesResponse", "type": "object", "properties": { "device": { "title": "ManagementDevicesResponseDevice", "type": "object", "properties": { "device_id": { "type": "string" }, "device_ip": { "type": "string" }, "management_type": { "type": "string" } }, "required": [ "device_id", "device_ip", "management_type" ], "additionalProperties": true } }, "required": [ "device" ], "additionalProperties": true }, "example": { "device": { "device_id": "edge-01", "device_ip": "192.0.2.10", "management_type": "inband" } } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Unprocessable content", "x-iris-problem-codes": [ "unprocessable-content" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#unprocessable-content", "title": "Unprocessable content", "status": 422, "code": "unprocessable-content" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementDevicesRequest", "type": "object", "properties": { "device_id": { "type": "string" }, "device_ip": { "type": "string" }, "management_type": { "type": "string", "enum": [ "routed", "inband", "router-routed", "router-nat", "xr-host" ] }, "model": { "type": "string" }, "credential_profile_id": { "type": "string" }, "iris_vlan": { "type": [ "string", "integer" ] }, "svi_ip": { "type": [ "string", "integer" ] }, "svi_mask": { "type": [ "string", "integer" ] }, "app_ip": { "type": [ "string", "integer" ] }, "app_mask": { "type": [ "string", "integer" ] }, "app_gateway": { "type": [ "string", "integer" ] }, "inband_vlan": { "type": [ "string", "integer" ] }, "ios_ssh_host": { "type": [ "string", "integer" ] }, "vpg_number": { "type": [ "string", "integer" ] }, "nat_interface": { "type": [ "string", "integer" ] }, "svi_igp": { "type": [ "string", "integer" ] }, "role": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "integer" ], "enum": [ "", "guestshell", "iox", "router", "xr-appmgr" ] } }, "required": [ "device_id", "device_ip", "management_type" ], "additionalProperties": false, "description": "Closed operator-owned fleet record. Unknown fields and the server-owned schema_version, registered_at, registration_id and os_family fields are rejected with 422." }, "example": { "device_id": "edge-01", "device_ip": "192.0.2.10", "management_type": "inband", "model": "C9300-48P", "credential_profile_id": "default" } } } } } }, "/internal/v1/devices/{device_id}": { "delete": { "operationId": "management_delete_internal_v1_devices_device_id", "summary": "Retire a device", "description": "Retire a device. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Retire a device response", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdResponse", "type": "object", "properties": { "deleted": { "type": "boolean" }, "degraded": { "type": "array", "items": { "type": "string" } } }, "required": [ "deleted", "degraded" ], "additionalProperties": true }, "example": { "deleted": true, "degraded": [] } } } }, "207": { "description": "Device retired but one or more non-authorizing cleanup steps degraded", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdPartialResponse", "type": "object", "properties": { "deleted": { "type": "boolean" }, "degraded": { "type": "array", "items": { "type": "string" } } }, "required": [ "deleted", "degraded" ], "additionalProperties": true }, "example": { "deleted": true, "degraded": [] } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/devices/export-csv": { "get": { "operationId": "management_get_internal_v1_devices_export_csv", "summary": "Export devices", "description": "Export devices. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "CSV document", "content": { "text/csv": { "schema": { "type": "string" }, "example": "device_id,device_ip\n" } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/devices/example-csv": { "get": { "operationId": "management_get_internal_v1_devices_example_csv", "summary": "Download example device CSV", "description": "Download example device CSV. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "CSV document", "content": { "text/csv": { "schema": { "type": "string" }, "example": "device_id,device_ip\n" } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/devices/import-csv": { "post": { "operationId": "management_post_internal_v1_devices_import_csv", "summary": "Import devices", "description": "Import devices. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. fleet batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Import devices response", "content": { "application/json": { "schema": { "title": "ManagementDevicesImportCsvResponse", "type": "object", "properties": { "imported": { "type": "integer" }, "new": { "type": "integer" }, "updated": { "type": "integer" }, "skipped": { "type": "integer" } }, "required": [ "imported", "new", "updated", "skipped" ], "additionalProperties": true }, "example": { "imported": 1, "new": 1, "updated": 0, "skipped": 0 } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "fleet batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "text/csv": { "schema": { "type": "string" }, "example": "device_id,device_ip\nedge-01,192.0.2.10\n" } } } } }, "/internal/v1/devices/bulk-credential": { "post": { "operationId": "management_post_internal_v1_devices_bulk_credential", "summary": "Assign credentials in bulk", "description": "Assign credentials in bulk. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. fleet batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Assign credentials in bulk response", "content": { "application/json": { "schema": { "title": "ManagementDevicesBulkCredentialResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "applied": { "type": "integer" }, "failed": { "title": "ManagementDevicesBulkCredentialResponseFailed", "type": "object", "properties": {}, "required": [], "additionalProperties": true } }, "required": [ "ok", "applied", "failed" ], "additionalProperties": true }, "example": { "ok": true, "applied": 1, "failed": {} } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "fleet batch action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementDevicesBulkCredentialRequest", "type": "object", "properties": { "device_ids": { "type": "array", "items": { "type": "string" } }, "credential_profile_id": { "type": "string" } }, "required": [ "device_ids", "credential_profile_id" ], "additionalProperties": true }, "example": { "device_ids": [ "edge-01" ], "credential_profile_id": "default" } } } } } }, "/internal/v1/devices/{device_id}/plan": { "get": { "operationId": "management_get_internal_v1_devices_device_id_plan", "summary": "Read device plan", "description": "Read device plan. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" } ], "responses": { "200": { "description": "Read device plan response", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdPlanResponse", "type": "object", "properties": { "plan": { "title": "ManagementDevicesDeviceIdPlanResponsePlan", "type": "object", "properties": { "plan_hash": { "type": "string" }, "resolved": { "title": "ManagementDevicesDeviceIdPlanResponsePlanResolved", "type": "object", "properties": { "platform": { "type": "string" }, "management_type": { "type": "string" } }, "required": [ "platform", "management_type" ], "additionalProperties": true } }, "required": [ "plan_hash", "resolved" ], "additionalProperties": true } }, "required": [ "plan" ], "additionalProperties": true }, "example": { "plan": { "plan_hash": "sha256:example", "resolved": { "platform": "iox", "management_type": "inband" } } } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/devices/{device_id}/reports": { "get": { "operationId": "management_get_internal_v1_devices_device_id_reports", "summary": "List device reports", "description": "List device reports. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" } ], "responses": { "200": { "description": "List device reports response", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdReportsResponse", "type": "object", "properties": { "device_id": { "type": "string" }, "observed_at": { "type": "number" }, "pending_request": { "oneOf": [ { "type": "object", "properties": { "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "requested_at": { "type": "number", "minimum": 0 }, "expires_at": { "type": "number", "minimum": 0 } }, "required": [ "request_id", "requested_at", "expires_at" ], "additionalProperties": false }, { "type": "null" } ] }, "reports": { "type": "array", "items": { "oneOf": [ { "title": "ManagementDevicesDeviceIdReportsResponseV2Report", "type": "object", "properties": { "v": { "type": "integer" }, "schema": { "type": "string", "const": "v2" }, "report_id": { "type": "string" }, "transfer_id": { "type": "string" }, "report_request_id": { "type": [ "string", "null" ] }, "report_created_at": { "type": "integer" }, "received_at": { "type": "integer" }, "image_id": { "type": "string" }, "event": { "type": "string" }, "stage_state": { "type": "string" }, "content_sha256": { "title": "ManagementDevicesDeviceIdReportsResponseV2ReportContent_Sha256", "type": "object", "properties": { "state": { "type": "string" }, "algo": { "type": "string" } }, "required": [ "state", "algo" ], "additionalProperties": true }, "ios_copy_verify": { "title": "ManagementDevicesDeviceIdReportsResponseV2ReportIos_Copy_Verify", "type": "object", "properties": { "state": { "type": "string" } }, "required": [ "state" ], "additionalProperties": true }, "sampling": { "title": "ManagementDevicesDeviceIdReportsResponseV2ReportSampling", "type": "object", "properties": { "sampling_class": { "type": "string" } }, "required": [ "sampling_class" ], "additionalProperties": true }, "peers": { "type": "array", "items": { "type": "string" } }, "peers_total": { "type": "integer" }, "peers_rows_dropped": { "type": "integer" }, "peers_truncated": { "type": "boolean" }, "peers_saturated": { "type": "boolean" } }, "required": [ "v", "schema", "report_id", "transfer_id", "report_request_id", "report_created_at", "received_at", "image_id", "event", "stage_state", "content_sha256", "ios_copy_verify", "sampling", "peers", "peers_total", "peers_rows_dropped", "peers_truncated", "peers_saturated" ], "additionalProperties": true }, { "title": "ManagementDevicesDeviceIdReportsResponseV1Report", "type": "object", "properties": { "schema": { "type": "string", "const": "v1" }, "event": { "type": "string" }, "image_id": { "type": "string" }, "peers": { "type": "array", "items": { "type": "string" } }, "peers_total": { "type": "integer" }, "peers_rows_dropped": { "type": "integer" }, "received_at": { "type": "integer" }, "_event_id": { "type": "string" } }, "required": [ "schema", "event", "image_id", "peers", "peers_total", "peers_rows_dropped", "received_at", "_event_id" ], "additionalProperties": true } ] } } }, "required": [ "device_id", "observed_at", "pending_request", "reports" ], "additionalProperties": true }, "example": { "device_id": "device-01", "observed_at": 1788470400.5, "pending_request": null, "reports": [ { "v": 2, "schema": "v2", "report_id": "7c1f0b9a2d3e4f5061728394a5b6c7d8", "transfer_id": "3f0a9c1d8e2b4a6f9017c3d5e7b1a2c4", "report_request_id": null, "report_created_at": 1788470300, "received_at": 1788470400, "image_id": "image-01", "event": "staging-complete", "stage_state": "ready", "content_sha256": { "state": "verified", "algo": "sha256" }, "ios_copy_verify": { "state": "ok" }, "sampling": { "sampling_class": "good" }, "peers": [], "peers_total": 0, "peers_rows_dropped": 0, "peers_truncated": false, "peers_saturated": false }, { "schema": "v1", "event": "seeding-only", "image_id": "image-01", "peers": [], "peers_total": 0, "peers_rows_dropped": 0, "received_at": 1788470400, "_event_id": "0123456789abcdef0123456789abcdef" } ] } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "422": { "description": "Unprocessable content", "x-iris-problem-codes": [ "unprocessable-content" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#unprocessable-content", "title": "Unprocessable content", "status": 422, "code": "unprocessable-content" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/devices/{device_id}/deployment": { "get": { "operationId": "management_get_internal_v1_devices_device_id_deployment", "summary": "Read device deployment", "description": "Read device deployment. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" } ], "responses": { "200": { "description": "Read device deployment response", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdDeploymentResponse", "type": "object", "properties": { "record": { "oneOf": [ { "title": "ManagementDevicesDeviceIdDeploymentResponseRecord", "type": "object", "properties": { "record_id": { "type": "string" }, "state": { "type": "string" } }, "required": [ "record_id", "state" ], "additionalProperties": true }, { "type": "null" } ] }, "total": { "type": "integer" } }, "required": [ "record", "total" ], "additionalProperties": true }, "example": { "record": null, "total": 0 } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/devices/{device_id}/certificate": { "get": { "operationId": "management_get_internal_v1_devices_device_id_certificate", "summary": "Read device peer certificate status", "description": "Read or withdraw one device's peer TLS certificate identity while retaining its inventory entry. The status 'active' means not revoked; it does not attest that a certificate has been issued or remains valid. Withdrawal requires TLS mode, the reviewed identity SHA256 and revision, and a UUID request_id. The durable request ID is bound to the device, identity and reviewed revision. Retrying the same request is safe; a conflicting review returns 409. A 503 may follow a completed write: GET reconciles the authoritative state. Revoked identities remain denied across restart and inventory removal. The reenroll action approves fresh onboarding for the same inventory entry and returns reenrollment-required; it does not restore old certificate access. Only explicit onboarding, after old catalog credentials are replaced durably, activates the new random certificate identity. Queued or running device jobs must finish first. The response does not prove peer-wide enforcement.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" } ], "responses": { "200": { "description": "Durable certificate identity withdrawal; not proof every peer has applied it", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_id": { "type": "string", "maxLength": 128 }, "identity_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "state": { "enum": [ "active", "revoked", "reenrollment-required" ] }, "revoked_at": { "type": [ "integer", "null" ], "minimum": 0 }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "recovery_request_id": { "type": [ "string", "null" ], "format": "uuid" }, "peer_tls_required": { "type": "boolean" }, "enforcement": { "enum": [ "pending", "not-applicable" ] } }, "required": [ "device_id", "identity_sha256", "revision", "state", "revoked_at", "request_id", "recovery_request_id", "peer_tls_required", "enforcement" ], "additionalProperties": false }, "example": { "device_id": "edge-01", "identity_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "revision": 1, "state": "revoked", "revoked_at": 1788470400, "request_id": "00000000-0000-0000-0000-000000000001", "recovery_request_id": null, "peer_tls_required": true, "enforcement": "pending" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/devices/{device_id}/certificate/revoke": { "post": { "operationId": "management_post_internal_v1_devices_device_id_certificate_revoke", "summary": "Revoke a device peer certificate", "description": "Read or withdraw one device's peer TLS certificate identity while retaining its inventory entry. The status 'active' means not revoked; it does not attest that a certificate has been issued or remains valid. Withdrawal requires TLS mode, the reviewed identity SHA256 and revision, and a UUID request_id. The durable request ID is bound to the device, identity and reviewed revision. Retrying the same request is safe; a conflicting review returns 409. A 503 may follow a completed write: GET reconciles the authoritative state. Revoked identities remain denied across restart and inventory removal. The reenroll action approves fresh onboarding for the same inventory entry and returns reenrollment-required; it does not restore old certificate access. Only explicit onboarding, after old catalog credentials are replaced durably, activates the new random certificate identity. Queued or running device jobs must finish first. The response does not prove peer-wide enforcement.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Durable certificate identity withdrawal; not proof every peer has applied it", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_id": { "type": "string", "maxLength": 128 }, "identity_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "state": { "enum": [ "active", "revoked", "reenrollment-required" ] }, "revoked_at": { "type": [ "integer", "null" ], "minimum": 0 }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "recovery_request_id": { "type": [ "string", "null" ], "format": "uuid" }, "peer_tls_required": { "type": "boolean" }, "enforcement": { "enum": [ "pending", "not-applicable" ] }, "applied": { "type": "boolean" } }, "required": [ "device_id", "identity_sha256", "revision", "state", "revoked_at", "request_id", "recovery_request_id", "peer_tls_required", "enforcement", "applied" ], "additionalProperties": false }, "example": { "device_id": "edge-01", "identity_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "revision": 1, "state": "revoked", "revoked_at": 1788470400, "request_id": "00000000-0000-0000-0000-000000000001", "recovery_request_id": null, "peer_tls_required": true, "enforcement": "pending", "applied": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdCertificateRevokeRequest", "type": "object", "properties": { "expected_revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "expected_identity_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "expected_revision", "expected_identity_sha256", "request_id" ], "additionalProperties": false }, "example": { "expected_revision": 0, "expected_identity_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "request_id": "00000000-0000-0000-0000-000000000001" } } } } } }, "/internal/v1/devices/{device_id}/certificate/reenroll": { "post": { "operationId": "management_post_internal_v1_devices_device_id_certificate_reenroll", "summary": "Approve fresh device certificate onboarding", "description": "Read or withdraw one device's peer TLS certificate identity while retaining its inventory entry. The status 'active' means not revoked; it does not attest that a certificate has been issued or remains valid. Withdrawal requires TLS mode, the reviewed identity SHA256 and revision, and a UUID request_id. The durable request ID is bound to the device, identity and reviewed revision. Retrying the same request is safe; a conflicting review returns 409. A 503 may follow a completed write: GET reconciles the authoritative state. Revoked identities remain denied across restart and inventory removal. The reenroll action approves fresh onboarding for the same inventory entry and returns reenrollment-required; it does not restore old certificate access. Only explicit onboarding, after old catalog credentials are replaced durably, activates the new random certificate identity. Queued or running device jobs must finish first. The response does not prove peer-wide enforcement.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Durable certificate identity withdrawal; not proof every peer has applied it", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_id": { "type": "string", "maxLength": 128 }, "identity_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "state": { "enum": [ "active", "revoked", "reenrollment-required" ] }, "revoked_at": { "type": [ "integer", "null" ], "minimum": 0 }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "recovery_request_id": { "type": [ "string", "null" ], "format": "uuid" }, "peer_tls_required": { "type": "boolean" }, "enforcement": { "enum": [ "pending", "not-applicable" ] }, "applied": { "type": "boolean" } }, "required": [ "device_id", "identity_sha256", "revision", "state", "revoked_at", "request_id", "recovery_request_id", "peer_tls_required", "enforcement", "applied" ], "additionalProperties": false }, "example": { "device_id": "edge-01", "identity_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "revision": 1, "state": "revoked", "revoked_at": 1788470400, "request_id": "00000000-0000-0000-0000-000000000001", "recovery_request_id": null, "peer_tls_required": true, "enforcement": "pending", "applied": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdCertificateReenrollRequest", "type": "object", "properties": { "expected_revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "expected_identity_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "expected_revision", "expected_identity_sha256", "request_id" ], "additionalProperties": false }, "example": { "expected_revision": 1, "expected_identity_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "request_id": "00000000-0000-0000-0000-000000000002" } } } } } }, "/internal/v1/devices/{device_id}/assign": { "post": { "operationId": "management_post_internal_v1_devices_device_id_assign", "summary": "Assign an image", "description": "Assign an image. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Assign an image response", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdAssignResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "assigned_image_ids": { "type": "array", "items": { "type": "string" } }, "removed_image_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "ok", "assigned_image_ids", "removed_image_ids" ], "additionalProperties": true }, "example": { "ok": true, "assigned_image_ids": [ "image-01" ], "removed_image_ids": [] } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Unprocessable content", "x-iris-problem-codes": [ "unprocessable-content" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#unprocessable-content", "title": "Unprocessable content", "status": 422, "code": "unprocessable-content" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdAssignRequest", "type": "object", "properties": { "image_ids": { "type": "array", "items": { "type": "string" } }, "expect_image_ids": { "type": "array", "items": { "type": "string" } }, "image_id": { "type": [ "string", "null" ] } }, "required": [], "additionalProperties": true, "description": "image_ids is the preferred ordered set and wins when both forms are present. image_id is the singular v1 compatibility form. An empty object, empty image_ids, or null image_id unassigns." }, "examples": { "orderedSet": { "value": { "image_ids": [ "image-01" ], "expect_image_ids": [] } }, "singularCompatibility": { "value": { "image_id": "image-01", "expect_image_ids": [] } }, "unassign": { "value": {} } } } } } } }, "/internal/v1/devices/{device_id}/credential": { "post": { "operationId": "management_post_internal_v1_devices_device_id_credential", "summary": "Assign a credential", "description": "Assign a credential. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Assign a credential response", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdCredentialResponse", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdCredentialRequest", "type": "object", "properties": { "credential_profile_id": { "type": "string" } }, "required": [ "credential_profile_id" ], "additionalProperties": true }, "example": { "credential_profile_id": "default" } } } } } }, "/internal/v1/devices/{device_id}/platform": { "post": { "operationId": "management_post_internal_v1_devices_device_id_platform", "summary": "Set device platform", "description": "Set device platform. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Set device platform response", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdPlatformResponse", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdPlatformRequest", "type": "object", "properties": { "platform": { "type": "string" } }, "required": [ "platform" ], "additionalProperties": true }, "example": { "platform": "iox" } } } } } }, "/internal/v1/devices/{device_id}/forget-host-key": { "post": { "operationId": "management_post_internal_v1_devices_device_id_forget_host_key", "summary": "Forget SSH host key", "description": "Forget SSH host key. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Forget SSH host key response", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdForgetHostKeyResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "peer": { "type": "string" } }, "required": [ "ok", "peer" ], "additionalProperties": true }, "example": { "ok": true, "peer": "192.0.2.10" } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdForgetHostKeyRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/internal/v1/devices/{device_id}/request-report": { "post": { "operationId": "management_post_internal_v1_devices_device_id_request_report", "summary": "Request a device report", "description": "Request a device report. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Request a device report response", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdRequestReportResponse", "type": "object", "properties": { "ok": { "const": true }, "device_id": { "type": "string" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "requested_at": { "type": "number" }, "expires_at": { "type": "number" } }, "required": [ "ok", "device_id", "request_id", "requested_at", "expires_at" ], "additionalProperties": true }, "example": { "ok": true, "device_id": "device-01", "request_id": "0123456789abcdef0123456789abcdef", "requested_at": 1788473400.5, "expires_at": 1788474000.5 } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Unprocessable content", "x-iris-problem-codes": [ "unprocessable-content" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#unprocessable-content", "title": "Unprocessable content", "status": 422, "code": "unprocessable-content" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdRequestReportRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/internal/v1/devices/{device_id}/peer-telemetry": { "post": { "operationId": "management_post_internal_v1_devices_device_id_peer_telemetry", "summary": "Set peer telemetry interval", "description": "Set peer telemetry interval. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "dry_run", "in": "query", "required": false, "description": "1 previews the locked candidate without persistence; 0 commits after required confirmation.", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "example": 1 }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "One exact strong policy ETag. Missing: 428; stale: 412; race under the policy lock: 409. Confirmation is candidate-bound at threshold zero, including every changed QoS document.", "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } ], "responses": { "200": { "description": "Set peer telemetry interval response", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdPeerTelemetryResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "revision": { "type": "integer" }, "candidate_revision": { "type": "integer" }, "dry_run": { "type": "boolean" }, "member_delta": { "type": "integer" }, "origin_access_lost": { "type": "integer" }, "empty_permitted_sets": { "type": "integer" }, "role_pairs_stopped": { "type": "integer" }, "qos_changed": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirm_token": { "type": [ "string", "null" ] }, "device_id": { "type": "string" }, "requested_interval_s": { "type": "integer" } }, "required": [ "ok", "revision", "candidate_revision", "dry_run", "member_delta", "origin_access_lost", "empty_permitted_sets", "role_pairs_stopped", "qos_changed", "requires_confirmation", "confirm_token", "device_id", "requested_interval_s" ], "additionalProperties": true }, "examples": { "confirmationRequired": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 1, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": true, "confirm_token": "candidate-bound-sha256", "device_id": "edge-01", "requested_interval_s": 10 } }, "noConfirmation": { "value": { "ok": true, "revision": 5, "candidate_revision": 5, "dry_run": true, "member_delta": 0, "origin_access_lost": 0, "empty_permitted_sets": 0, "role_pairs_stopped": 0, "qos_changed": false, "requires_confirmation": false, "confirm_token": null, "device_id": "edge-01", "requested_interval_s": 10 } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "example": "\"iris-peer-policy-4\"" } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Device not found or Route not found", "x-iris-problem-codes": [ "device_not_found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "device_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#device_not_found", "title": "Device not found", "status": 404, "code": "device_not_found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "409": { "description": "Operation backlog full or Revision conflict", "x-iris-problem-codes": [ "operation_backlog_full", "revision_conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "operation_backlog_full": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#operation_backlog_full", "title": "Operation backlog full", "status": 409, "code": "operation_backlog_full" } }, "revision_conflict": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#revision_conflict", "title": "Revision conflict", "status": 409, "code": "revision_conflict" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid policy or Invalid policy request or Peer telemetry unsupported", "x-iris-problem-codes": [ "invalid_policy", "invalid_policy_request", "peer_telemetry_unsupported" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_policy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy", "title": "Invalid policy", "status": 422, "code": "invalid_policy" } }, "invalid_policy_request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_policy_request", "title": "Invalid policy request", "status": 422, "code": "invalid_policy_request" } }, "peer_telemetry_unsupported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#peer_telemetry_unsupported", "title": "Peer telemetry unsupported", "status": 422, "code": "peer_telemetry_unsupported" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "428": { "description": "Confirmation required or Precondition required", "x-iris-problem-codes": [ "confirmation_required", "precondition_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "confirmation_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#confirmation_required", "title": "Confirmation required", "status": 428, "code": "confirmation_required" } }, "precondition_required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Policy unavailable or Service unavailable", "x-iris-problem-codes": [ "policy_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_unavailable", "title": "Policy unavailable", "status": 503, "code": "policy_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "schema": { "type": "string" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdPeerTelemetryRequest", "type": "object", "properties": { "interval_s": { "type": "integer", "enum": [ 10, 60 ] }, "confirm_token": { "type": [ "string", "null" ], "writeOnly": true } }, "required": [ "interval_s" ], "additionalProperties": false }, "example": { "interval_s": 10, "confirm_token": "candidate-bound-sha256" } } } } } }, "/internal/v1/devices/{device_id}/adopt": { "post": { "operationId": "management_post_internal_v1_devices_device_id_adopt", "summary": "Adopt a deployment", "description": "Adopt a deployment. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Adopt a deployment response", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdAdoptResponse", "type": "object", "properties": { "record_id": { "type": "string" } }, "required": [ "record_id" ], "additionalProperties": true }, "example": { "record_id": "record-01" } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdAdoptRequest", "type": "object", "properties": { "acknowledge_adopt": { "type": "boolean" } }, "required": [ "acknowledge_adopt" ], "additionalProperties": true }, "example": { "acknowledge_adopt": true } } } } } }, "/internal/v1/devices/{device_id}/onboard": { "post": { "operationId": "management_post_internal_v1_devices_device_id_onboard", "summary": "Start device onboarding", "description": "Start device onboarding. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Start device onboarding response", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdOnboardResponse", "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ], "additionalProperties": true }, "example": { "job_id": "job-01" } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdOnboardRequest", "type": "object", "properties": { "telemetry": { "type": "boolean" }, "telemetry_stream": { "type": "boolean" }, "log": { "type": "boolean", "default": false, "description": "Enable detailed IOx command output in the job log. Onboarding also enables download logs on IOx and IOS-XR. Guest Shell logging is configured separately." } }, "required": [], "additionalProperties": true }, "example": { "telemetry": true, "telemetry_stream": false, "log": false } } } } } }, "/internal/v1/devices/{device_id}/undeploy": { "post": { "operationId": "management_post_internal_v1_devices_device_id_undeploy", "summary": "Start device removal", "description": "Start device removal. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Start device removal response", "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdUndeployResponse", "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ], "additionalProperties": true }, "example": { "job_id": "job-01" } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "device workflow action: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementDevicesDeviceIdUndeployRequest", "type": "object", "properties": { "force": { "type": "boolean" }, "log": { "type": "boolean", "default": false, "description": "Enable detailed IOx command output in the job log. Onboarding also enables download logs on IOx and IOS-XR. Guest Shell logging is configured separately." } }, "required": [], "additionalProperties": true }, "example": { "force": false, "log": false } } } } } }, "/internal/v1/install-options": { "get": { "operationId": "management_get_internal_v1_install_options", "summary": "List install options", "description": "List install options. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Without management_type, this retains the model-only response; null means no model-based restriction. With management_type, options is always an array of choices accepted for that model and management pair; an incompatible pair or invalid type returns an empty array. Management type alone controls network-field visibility in the Console. A saved free-text model does not confirm hardware support.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "model", "in": "query", "required": false, "description": "Device model used to derive supported install methods", "schema": { "type": "string" }, "example": "IE-3400" }, { "name": "management_type", "in": "query", "required": false, "description": "Restrict to the model and management pair; blank or unknown types return no options", "schema": { "type": "string" }, "example": "inband" } ], "responses": { "200": { "description": "List install options response", "content": { "application/json": { "schema": { "title": "ManagementInstallOptionsResponse", "type": "object", "properties": { "options": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "options" ], "additionalProperties": true }, "example": { "options": [ "guestshell", "iox" ] } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/credentials": { "get": { "operationId": "management_get_internal_v1_credentials", "summary": "List credential profiles", "description": "List credential profiles. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. This bounded v1 collection has no pagination parameter; adding one without a stable compatibility shape is deferred to the next major version.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "List credential profiles response", "content": { "application/json": { "schema": { "title": "ManagementCredentialsResponse", "type": "object", "properties": { "profiles": { "type": "array", "items": { "title": "ManagementCredentialsResponseProfilesItem", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "device_user": { "type": "string" } }, "required": [ "id", "name", "device_user" ], "additionalProperties": true } } }, "required": [ "profiles" ], "additionalProperties": true }, "example": { "profiles": [ { "id": "default", "name": "Default devices", "device_user": "operator" } ] } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "management_post_internal_v1_credentials", "summary": "Create a credential profile", "description": "Create a credential profile. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Create a credential profile response", "content": { "application/json": { "schema": { "title": "ManagementCredentialsResponse", "type": "object", "properties": { "profile": { "title": "ManagementCredentialsResponseProfile", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "device_user": { "type": "string" } }, "required": [ "id", "name", "device_user" ], "additionalProperties": true } }, "required": [ "profile" ], "additionalProperties": true }, "example": { "profile": { "id": "default", "name": "Default devices", "device_user": "operator" } } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementCredentialsRequest", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "device_user": { "type": "string", "description": "Must not contain U+0000 (NUL)." }, "device_pass": { "type": "string", "format": "password", "writeOnly": true, "description": "Must not contain U+0000 (NUL)." }, "enable_secret": { "type": "string", "format": "password", "writeOnly": true, "description": "Must not contain U+0000 (NUL)." } }, "required": [ "id", "name", "device_user", "device_pass" ], "additionalProperties": true }, "example": { "id": "default", "name": "Default devices", "device_user": "operator", "device_pass": "device-password", "enable_secret": "enable-password" } } } } } }, "/internal/v1/credentials/{credential_id}": { "delete": { "operationId": "management_delete_internal_v1_credentials_credential_id", "summary": "Delete a credential profile", "description": "Delete a credential profile. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "credential_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Delete a credential profile response", "content": { "application/json": { "schema": { "title": "ManagementCredentialsCredentialIdResponse", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": true }, "example": { "deleted": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/onboard/jobs": { "get": { "operationId": "management_get_internal_v1_onboard_jobs", "summary": "List onboarding jobs", "description": "List onboarding jobs. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. This bounded v1 collection has no pagination parameter; adding one without a stable compatibility shape is deferred to the next major version.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "List onboarding jobs response", "content": { "application/json": { "schema": { "title": "ManagementOnboardJobsResponse", "type": "object", "properties": { "jobs": { "type": "array", "items": { "title": "ManagementOnboardJobsResponseJobsItem", "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "state" ], "additionalProperties": true } }, "max_concurrent": { "type": "integer" }, "now": { "type": "integer" } }, "required": [ "jobs", "max_concurrent", "now" ], "additionalProperties": true }, "example": { "jobs": [ { "id": "job-01", "state": "running" } ], "max_concurrent": 4, "now": 1788470400 } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/onboard/jobs/{job_id}": { "get": { "operationId": "management_get_internal_v1_onboard_jobs_job_id", "summary": "Read onboarding job", "description": "Read onboarding job. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" } ], "responses": { "200": { "description": "Read onboarding job response", "content": { "application/json": { "schema": { "title": "ManagementOnboardJobsJobIdResponse", "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "device_id": { "type": "string" } }, "required": [ "id", "state", "device_id" ], "additionalProperties": true }, "example": { "id": "job-01", "state": "running", "device_id": "edge-01" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/onboard/jobs/{job_id}/stream": { "get": { "operationId": "management_get_internal_v1_onboard_jobs_job_id_stream", "summary": "Stream onboarding job output", "description": "Stream onboarding job output. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" } ], "responses": { "200": { "description": "Job log lines as unnamed text data events, with keepalive comments. An end event carries done, error, cancelled, idle, or unknown. Each connection replays the retained lines from the start; Last-Event-ID is not supported.", "content": { "text/event-stream": { "itemSchema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string" }, "event": { "enum": [ "message", "end" ] } }, "if": { "required": [ "event" ], "properties": { "event": { "const": "end" } } }, "then": { "properties": { "data": { "enum": [ "done", "error", "cancelled", "idle", "unknown" ] } } } }, "examples": { "completed": { "summary": "A log line followed by completion", "serializedValue": "data: onboard complete: 192.0.2.10\n\nevent: end\ndata: done\n\n" } } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/onboard/jobs/{job_id}/abort": { "post": { "operationId": "management_post_internal_v1_onboard_jobs_job_id_abort", "summary": "Abort onboarding job", "description": "Abort onboarding job. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. onboarding job control: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Abort onboarding job response", "content": { "application/json": { "schema": { "title": "ManagementOnboardJobsJobIdAbortResponse", "type": "object", "properties": { "aborted": { "type": "boolean" } }, "required": [ "aborted" ], "additionalProperties": true }, "example": { "aborted": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "onboarding job control: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementOnboardJobsJobIdAbortRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/internal/v1/onboard/cancel-queued": { "post": { "operationId": "management_post_internal_v1_onboard_cancel_queued", "summary": "Cancel queued onboarding jobs", "description": "Cancel queued onboarding jobs. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. onboarding job control: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Cancel queued onboarding jobs response", "content": { "application/json": { "schema": { "title": "ManagementOnboardCancelQueuedResponse", "type": "object", "properties": { "cancelled": { "type": "integer" } }, "required": [ "cancelled" ], "additionalProperties": true }, "example": { "cancelled": 1 } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "onboarding job control: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementOnboardCancelQueuedRequest", "type": "object", "properties": { "job_ids": { "type": "array", "items": { "type": "string" } } }, "required": [], "additionalProperties": true }, "example": { "job_ids": [ "job-01" ] } } } } } }, "/internal/v1/deploy-logs": { "get": { "operationId": "management_get_internal_v1_deploy_logs", "summary": "List deployment logs", "description": "List deployment logs. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "device_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "edge-01" }, { "name": "after_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788384000 }, { "name": "before_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788470400 } ], "responses": { "200": { "description": "List deployment logs response", "content": { "application/json": { "schema": { "title": "ManagementDeployLogsResponse", "type": "object", "properties": { "logs": { "type": "array", "items": { "title": "ManagementDeployLogsResponseLogsItem", "type": "object", "properties": { "file": { "type": "string" }, "device_id": { "type": "string" }, "action": { "type": "string" }, "state": { "type": "string" }, "rc": { "type": "integer" }, "finished_at": { "type": "integer" }, "size": { "type": "integer" } }, "required": [ "file", "device_id", "action", "state", "rc", "finished_at", "size" ], "additionalProperties": true } } }, "required": [ "logs" ], "additionalProperties": true }, "example": { "logs": [ { "file": "1788470400-edge-01-onboard-job-01.log", "device_id": "edge-01", "action": "onboard", "state": "done", "rc": 0, "finished_at": 1788470400, "size": 1024 } ] } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/deploy-logs/histogram": { "get": { "operationId": "management_get_internal_v1_deploy_logs_histogram", "summary": "Read deployment log histogram", "description": "Read deployment log histogram. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "device_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "edge-01" }, { "name": "buckets", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "example": 30 }, { "name": "window", "in": "query", "required": false, "schema": { "type": "number", "minimum": 60 }, "example": 604800 }, { "name": "since_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788384000 }, { "name": "until_ts", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1788470400 } ], "responses": { "200": { "description": "Read deployment log histogram response", "content": { "application/json": { "schema": { "title": "ManagementDeployLogsHistogramResponse", "type": "object", "properties": { "buckets": { "type": "array", "items": { "title": "ManagementDeployLogsHistogramResponseBucketsItem", "type": "object", "properties": { "start": { "type": "integer" }, "count": { "type": "integer" } }, "required": [ "start", "count" ], "additionalProperties": true } }, "now": { "type": "integer" } }, "required": [ "buckets", "now" ], "additionalProperties": true }, "example": { "buckets": [ { "start": 1788470400, "count": 1 } ], "now": 1788474000 } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/deploy-logs/{filename}": { "get": { "operationId": "management_get_internal_v1_deploy_logs_filename", "summary": "Read deployment log", "description": "Read deployment log. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "filename", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" } ], "responses": { "200": { "description": "Deployment log text", "content": { "text/plain": { "schema": { "type": "string" }, "example": "onboard started\n" } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/overview": { "get": { "operationId": "management_get_internal_v1_overview", "summary": "Read fleet overview", "description": "Read fleet overview. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read fleet overview response", "content": { "application/json": { "schema": { "title": "ManagementOverviewResponse", "type": "object", "properties": { "images": { "type": "integer" }, "devices": { "type": "integer" }, "assigned": { "type": "integer" }, "staged": { "type": "integer" }, "staging_now": { "type": "integer" }, "awaiting_heartbeat": { "type": "integer" }, "rollout": { "type": "array", "items": { "title": "ManagementOverviewResponseRolloutItem", "type": "object", "properties": { "image_id": { "type": "string" }, "filename": { "type": "string" }, "assigned": { "type": "integer" }, "staged": { "type": "integer" } }, "required": [ "image_id", "filename", "assigned", "staged" ], "additionalProperties": true } }, "swarm_map_url": { "type": "string" } }, "required": [ "images", "devices", "assigned", "staged", "staging_now", "awaiting_heartbeat", "rollout", "swarm_map_url" ], "additionalProperties": true }, "example": { "images": 1, "devices": 1, "assigned": 1, "staged": 1, "staging_now": 0, "awaiting_heartbeat": 0, "rollout": [ { "image_id": "image-01", "filename": "image.bin", "assigned": 1, "staged": 1 } ], "swarm_map_url": "/swarmmap" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Device status temporarily busy or Service unavailable", "x-iris-problem-codes": [ "projection-busy", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "projection-busy": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#projection-busy", "title": "Device status temporarily busy", "status": 503, "code": "projection-busy" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/deployment": { "get": { "operationId": "management_get_internal_v1_deployment", "summary": "Read deployment layout and runtime inventory", "description": "Read deployment layout and runtime inventory. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read-only deployment inventory or explicitly limited runtime observations", "content": { "application/json": { "schema": { "type": "object", "properties": { "layout": { "enum": [ "docker", "docker-split", "kubernetes", "single-container", "unknown" ] }, "source": { "enum": [ "managed-worker", "runtime" ] }, "observed_at": { "type": "integer", "minimum": 0 }, "instance": { "type": [ "string", "null" ], "maxLength": 256 }, "namespace": { "type": [ "string", "null" ], "maxLength": 256 }, "note": { "type": [ "string", "null" ], "maxLength": 256 }, "components": { "type": "array", "maxItems": 64, "items": { "type": "object", "properties": { "role": { "enum": [ "server", "console" ] }, "kind": { "enum": [ "container", "pod", "process" ] }, "name": { "type": [ "string", "null" ], "maxLength": 256 }, "host": { "type": [ "string", "null" ], "maxLength": 256 }, "address": { "type": [ "string", "null" ], "maxLength": 256 }, "image": { "type": [ "string", "null" ], "maxLength": 256 }, "state": { "type": [ "string", "null" ], "maxLength": 256 }, "os": { "type": [ "string", "null" ], "maxLength": 256 }, "architecture": { "type": [ "string", "null" ], "maxLength": 256 }, "kernel": { "type": [ "string", "null" ], "maxLength": 256 } }, "required": [ "role", "kind", "name", "host", "address", "image", "state", "os", "architecture", "kernel" ], "additionalProperties": false } } }, "required": [ "layout", "source", "observed_at", "instance", "namespace", "note", "components" ], "additionalProperties": false }, "example": { "layout": "docker", "source": "managed-worker", "observed_at": 1788470400, "instance": "iris", "namespace": null, "note": null, "components": [ { "role": "server", "kind": "container", "name": "iris-server", "host": "staging-host", "address": null, "image": "iris:latest", "state": "running / healthy", "os": "Debian GNU/Linux", "architecture": "x86_64", "kernel": "6.8.0" } ] } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/swarm": { "get": { "operationId": "management_get_internal_v1_swarm", "summary": "Read swarm state", "description": "Read swarm state. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Image rows include image_id when the torrent hash maps to one catalog image. Observations and reports carry image_id when known; match it before attributing measurements. Tracker seeder role does not establish device staging completion, and ambiguous peer rates remain unavailable.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Peer page size; omit for the complete compatibility response", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "example": 100 }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "example": 0 } ], "responses": { "200": { "description": "Whole swarm, an opt-in peer page, or an availability fallback", "content": { "application/json": { "schema": { "oneOf": [ { "title": "ManagementSwarmWholeResponse", "type": "object", "properties": { "now": { "type": "number" }, "server": { "title": "ManagementSwarmWholeResponseServer", "type": "object", "properties": { "host": { "type": "string" }, "server_observation": { "title": "ManagementSwarmWholeResponseServerServer_Observation", "type": "object", "properties": { "observed_at": { "type": [ "number", "null" ] }, "rpc_up": { "type": "boolean" }, "unavailable": { "type": "boolean" }, "aria_session_id": { "type": [ "string", "null" ] }, "peer_tls": { "type": "object", "additionalProperties": false, "required": [ "runtime_mode", "runtime_source" ], "properties": { "runtime_mode": { "enum": [ "disabled", "required", "unknown" ] }, "runtime_source": { "enum": [ "aria2_rpc", "unknown" ] }, "revocations": { "type": "object", "properties": { "supported": { "const": true }, "mode": { "enum": [ "required", "disabled" ] }, "state": { "enum": [ "valid", "unavailable", "expired" ] }, "authority": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "issued_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "expires_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "own_revoked": { "type": "boolean" }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "supported", "mode", "state", "authority", "revision", "issued_at", "expires_at", "own_revoked", "observed_at" ], "additionalProperties": false }, "reported_at": { "type": [ "number", "null" ] } }, "description": "Last reported torrent TLS daemon policy, not negotiated connection evidence. Missing means unknown." } }, "required": [ "observed_at", "rpc_up", "unavailable", "aria_session_id" ], "additionalProperties": true } }, "required": [ "host", "server_observation" ], "additionalProperties": true }, "images": { "type": "array", "items": { "title": "ManagementSwarmWholeResponseImagesItem", "type": "object", "properties": { "image": { "type": "string" }, "info_hash": { "type": "string" }, "total_bytes": { "type": [ "integer", "null" ] }, "seeders": { "type": "integer" }, "leechers": { "type": "integer" }, "peers": { "type": "array", "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "ip", "port", "tracker", "device_id" ], "properties": { "ip": { "type": "string" }, "port": { "type": "integer" }, "tracker": { "type": "object", "additionalProperties": false, "required": [ "principal_type", "role", "left", "last_seen", "progress", "principal_id" ], "properties": { "principal_type": { "const": "device" }, "role": { "enum": [ "seeder", "leecher" ] }, "left": { "type": [ "integer", "null" ] }, "last_seen": { "type": [ "number", "null" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "principal_id": { "type": "string" } } }, "device_observation": { "type": "object" }, "server_observation": { "type": "object" }, "latest_report": { "type": "object" }, "peer_policy": { "type": "object" }, "peer_enforcement": { "type": "object" }, "device_id": { "type": "string" }, "peer_tls": { "type": "object", "additionalProperties": false, "required": [ "configured_mode", "runtime_mode", "runtime_source" ], "properties": { "configured_mode": { "enum": [ "disabled", "required" ] }, "runtime_mode": { "enum": [ "disabled", "required", "unknown" ] }, "runtime_source": { "enum": [ "aria2_rpc", "unknown" ] }, "revocations": { "type": "object", "properties": { "supported": { "const": true }, "mode": { "enum": [ "required", "disabled" ] }, "state": { "enum": [ "valid", "unavailable", "expired" ] }, "authority": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "issued_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "expires_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "own_revoked": { "type": "boolean" }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "supported", "mode", "state", "authority", "revision", "issued_at", "expires_at", "own_revoked", "observed_at" ], "additionalProperties": false }, "reported_at": { "type": [ "number", "null" ] } }, "description": "Last reported torrent TLS daemon policy, not negotiated connection evidence. Missing means unknown." }, "peer_telemetry": { "type": "object", "additionalProperties": false, "properties": { "supported": { "type": "boolean" }, "requested_interval_s": { "enum": [ 10, 60, null ] }, "effective_interval_s": { "type": [ "integer", "null" ] } } }, "model": { "type": "string" }, "current_image_id": { "type": "string" }, "stage_state": { "type": "string" }, "staged_image_ids": { "type": "array", "items": { "type": "string" } }, "errored_image_ids": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": [ "ip", "port", "tracker" ], "properties": { "ip": { "type": "string" }, "port": { "type": "integer" }, "tracker": { "type": "object", "additionalProperties": false, "required": [ "principal_type", "role", "left", "last_seen", "progress", "principal_id" ], "properties": { "principal_type": { "const": "service" }, "role": { "enum": [ "seeder", "leecher" ] }, "left": { "type": [ "integer", "null" ] }, "last_seen": { "type": [ "number", "null" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "principal_id": { "type": "string" } } }, "device_observation": { "type": "object" }, "server_observation": { "type": "object" }, "latest_report": { "type": "object" }, "peer_policy": { "type": "object" }, "peer_enforcement": { "type": "object" } } }, { "type": "object", "additionalProperties": false, "required": [ "ip", "port", "tracker" ], "properties": { "ip": { "type": "string" }, "port": { "type": "integer" }, "tracker": { "type": "object", "additionalProperties": false, "required": [ "principal_type", "role", "left", "last_seen", "progress" ], "properties": { "principal_type": { "const": "legacy" }, "role": { "enum": [ "seeder", "leecher" ] }, "left": { "type": [ "integer", "null" ] }, "last_seen": { "type": [ "number", "null" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "participant_class": { "type": "string" } } }, "device_id": { "type": "null" }, "warning": { "const": "legacy_unattributed" }, "quarantine_available": { "const": false } } } ] } }, "peer_edges": { "type": "array", "maxItems": 1024, "items": { "type": "object", "properties": { "source_device_id": { "type": "string" }, "target_device_id": { "type": "string" }, "reporter_device_id": { "type": "string" }, "bytes_per_second": { "type": "integer", "minimum": 1 }, "connection_count": { "type": "integer", "minimum": 1, "maximum": 32 }, "rate_field": { "enum": [ "send_bps", "receive_bps" ] }, "identity_basis": { "enum": [ "tracker_endpoint", "unique_tracker_address" ] }, "received_at": { "type": "number" }, "observed_at": { "type": [ "number", "null" ] }, "age_s": { "type": "integer", "minimum": 0 }, "valid_for_s": { "type": "integer", "minimum": 1, "maximum": 120 } }, "required": [ "source_device_id", "target_device_id", "reporter_device_id", "bytes_per_second", "connection_count", "rate_field", "identity_basis", "received_at", "observed_at", "age_s", "valid_for_s" ], "additionalProperties": false } }, "peer_edges_truncated": { "type": "boolean" }, "unattributed_peer_connections": { "type": "integer", "minimum": 0 } }, "required": [ "image", "info_hash", "total_bytes", "seeders", "leechers", "peers" ], "additionalProperties": true } } }, "required": [ "now", "server", "images" ], "additionalProperties": false }, { "title": "ManagementSwarmPageResponse", "type": "object", "properties": { "now": { "type": "number" }, "server": { "title": "ManagementSwarmPageResponseServer", "type": "object", "properties": { "host": { "type": "string" }, "server_observation": { "title": "ManagementSwarmPageResponseServerServer_Observation", "type": "object", "properties": { "observed_at": { "type": [ "number", "null" ] }, "rpc_up": { "type": "boolean" }, "unavailable": { "type": "boolean" }, "aria_session_id": { "type": [ "string", "null" ] }, "peer_tls": { "type": "object", "additionalProperties": false, "required": [ "runtime_mode", "runtime_source" ], "properties": { "runtime_mode": { "enum": [ "disabled", "required", "unknown" ] }, "runtime_source": { "enum": [ "aria2_rpc", "unknown" ] }, "revocations": { "type": "object", "properties": { "supported": { "const": true }, "mode": { "enum": [ "required", "disabled" ] }, "state": { "enum": [ "valid", "unavailable", "expired" ] }, "authority": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "issued_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "expires_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "own_revoked": { "type": "boolean" }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "supported", "mode", "state", "authority", "revision", "issued_at", "expires_at", "own_revoked", "observed_at" ], "additionalProperties": false }, "reported_at": { "type": [ "number", "null" ] } }, "description": "Last reported torrent TLS daemon policy, not negotiated connection evidence. Missing means unknown." } }, "required": [ "observed_at", "rpc_up", "unavailable", "aria_session_id" ], "additionalProperties": true } }, "required": [ "host", "server_observation" ], "additionalProperties": true }, "images": { "type": "array", "items": { "title": "ManagementSwarmPageResponseImagesItem", "type": "object", "properties": { "image": { "type": "string" }, "info_hash": { "type": "string" }, "total_bytes": { "type": [ "integer", "null" ] }, "seeders": { "type": "integer" }, "leechers": { "type": "integer" }, "peers": { "type": "array", "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "ip", "port", "tracker", "device_id" ], "properties": { "ip": { "type": "string" }, "port": { "type": "integer" }, "tracker": { "type": "object", "additionalProperties": false, "required": [ "principal_type", "role", "left", "last_seen", "progress", "principal_id" ], "properties": { "principal_type": { "const": "device" }, "role": { "enum": [ "seeder", "leecher" ] }, "left": { "type": [ "integer", "null" ] }, "last_seen": { "type": [ "number", "null" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "principal_id": { "type": "string" } } }, "device_observation": { "type": "object" }, "server_observation": { "type": "object" }, "latest_report": { "type": "object" }, "peer_policy": { "type": "object" }, "peer_enforcement": { "type": "object" }, "device_id": { "type": "string" }, "peer_tls": { "type": "object", "additionalProperties": false, "required": [ "configured_mode", "runtime_mode", "runtime_source" ], "properties": { "configured_mode": { "enum": [ "disabled", "required" ] }, "runtime_mode": { "enum": [ "disabled", "required", "unknown" ] }, "runtime_source": { "enum": [ "aria2_rpc", "unknown" ] }, "revocations": { "type": "object", "properties": { "supported": { "const": true }, "mode": { "enum": [ "required", "disabled" ] }, "state": { "enum": [ "valid", "unavailable", "expired" ] }, "authority": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "issued_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "expires_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "own_revoked": { "type": "boolean" }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "supported", "mode", "state", "authority", "revision", "issued_at", "expires_at", "own_revoked", "observed_at" ], "additionalProperties": false }, "reported_at": { "type": [ "number", "null" ] } }, "description": "Last reported torrent TLS daemon policy, not negotiated connection evidence. Missing means unknown." }, "peer_telemetry": { "type": "object", "additionalProperties": false, "properties": { "supported": { "type": "boolean" }, "requested_interval_s": { "enum": [ 10, 60, null ] }, "effective_interval_s": { "type": [ "integer", "null" ] } } }, "model": { "type": "string" }, "current_image_id": { "type": "string" }, "stage_state": { "type": "string" }, "staged_image_ids": { "type": "array", "items": { "type": "string" } }, "errored_image_ids": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": [ "ip", "port", "tracker" ], "properties": { "ip": { "type": "string" }, "port": { "type": "integer" }, "tracker": { "type": "object", "additionalProperties": false, "required": [ "principal_type", "role", "left", "last_seen", "progress", "principal_id" ], "properties": { "principal_type": { "const": "service" }, "role": { "enum": [ "seeder", "leecher" ] }, "left": { "type": [ "integer", "null" ] }, "last_seen": { "type": [ "number", "null" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "principal_id": { "type": "string" } } }, "device_observation": { "type": "object" }, "server_observation": { "type": "object" }, "latest_report": { "type": "object" }, "peer_policy": { "type": "object" }, "peer_enforcement": { "type": "object" } } }, { "type": "object", "additionalProperties": false, "required": [ "ip", "port", "tracker" ], "properties": { "ip": { "type": "string" }, "port": { "type": "integer" }, "tracker": { "type": "object", "additionalProperties": false, "required": [ "principal_type", "role", "left", "last_seen", "progress" ], "properties": { "principal_type": { "const": "legacy" }, "role": { "enum": [ "seeder", "leecher" ] }, "left": { "type": [ "integer", "null" ] }, "last_seen": { "type": [ "number", "null" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "participant_class": { "type": "string" } } }, "device_id": { "type": "null" }, "warning": { "const": "legacy_unattributed" }, "quarantine_available": { "const": false } } } ] } }, "peer_edges": { "type": "array", "maxItems": 1024, "items": { "type": "object", "properties": { "source_device_id": { "type": "string" }, "target_device_id": { "type": "string" }, "reporter_device_id": { "type": "string" }, "bytes_per_second": { "type": "integer", "minimum": 1 }, "connection_count": { "type": "integer", "minimum": 1, "maximum": 32 }, "rate_field": { "enum": [ "send_bps", "receive_bps" ] }, "identity_basis": { "enum": [ "tracker_endpoint", "unique_tracker_address" ] }, "received_at": { "type": "number" }, "observed_at": { "type": [ "number", "null" ] }, "age_s": { "type": "integer", "minimum": 0 }, "valid_for_s": { "type": "integer", "minimum": 1, "maximum": 120 } }, "required": [ "source_device_id", "target_device_id", "reporter_device_id", "bytes_per_second", "connection_count", "rate_field", "identity_basis", "received_at", "observed_at", "age_s", "valid_for_s" ], "additionalProperties": false } }, "peer_edges_truncated": { "type": "boolean" }, "unattributed_peer_connections": { "type": "integer", "minimum": 0 } }, "required": [ "image", "info_hash", "total_bytes", "seeders", "leechers", "peers" ], "additionalProperties": true } }, "peers_total": { "type": "integer" }, "peers_offset": { "type": "integer" }, "peers_limit": { "type": [ "integer", "null" ] } }, "required": [ "now", "server", "images", "peers_total", "peers_offset", "peers_limit" ], "additionalProperties": false }, { "title": "ManagementSwarmUnavailableResponse", "type": "object", "properties": { "peers": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } }, "required": [ "peers", "error" ], "additionalProperties": false } ] }, "examples": { "whole": { "value": { "now": 1788470400.0, "server": { "host": "192.0.2.1", "server_observation": { "observed_at": 1788470400, "rpc_up": true, "unavailable": false, "aria_session_id": "session-01" } }, "images": [ { "image": "image.bin", "info_hash": "0000000000000000000000000000000000000000", "total_bytes": 1048576, "seeders": 1, "leechers": 0, "peers": [ { "device_id": "edge-01", "ip": "192.0.2.10", "port": 6881, "tracker": { "principal_type": "device", "principal_id": "edge-01", "role": "seeder", "left": 0, "last_seen": 1788470400.0, "progress": 1.0 } } ] } ] } }, "page": { "value": { "now": 1788470400.0, "server": { "host": "192.0.2.1", "server_observation": { "observed_at": 1788470400, "rpc_up": true, "unavailable": false, "aria_session_id": "session-01" } }, "images": [ { "image": "image.bin", "info_hash": "0000000000000000000000000000000000000000", "total_bytes": 1048576, "seeders": 1, "leechers": 0, "peers": [ { "device_id": "edge-01", "ip": "192.0.2.10", "port": 6881, "tracker": { "principal_type": "device", "principal_id": "edge-01", "role": "seeder", "left": 0, "last_seen": 1788470400.0, "progress": 1.0 } } ] } ], "peers_total": 1, "peers_offset": 0, "peers_limit": 100 } }, "unavailable": { "value": { "peers": [], "error": "swarm data unavailable" } } } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/telemetry/health": { "get": { "operationId": "management_get_internal_v1_telemetry_health", "summary": "Read telemetry health", "description": "Read telemetry health. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Detailed exporter status or a non-secret availability fallback", "content": { "application/json": { "schema": { "oneOf": [ { "title": "ManagementTelemetryHealthResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "otlp_export": { "title": "ManagementTelemetryHealthResponseOtlp_Export", "type": "object", "properties": { "state": { "type": "string" }, "signals": { "title": "ManagementTelemetryHealthResponseOtlp_ExportSignals", "type": "object", "properties": {}, "required": [], "additionalProperties": true } }, "required": [ "state", "signals" ], "additionalProperties": true } }, "required": [ "ok", "otlp_export" ], "additionalProperties": false }, { "title": "ManagementTelemetryHealthUnavailableResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "ok", "error" ], "additionalProperties": false } ] }, "examples": { "healthy": { "value": { "ok": true, "otlp_export": { "state": "healthy", "signals": {} } } }, "unavailable": { "value": { "ok": false, "error": "unavailable" } } } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/telemetry/stream": { "post": { "operationId": "management_post_internal_v1_telemetry_stream", "summary": "Proxy telemetry stream", "description": "Proxy telemetry stream. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. telemetry stream control: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Proxy telemetry stream response", "content": { "application/json": { "schema": { "title": "ManagementTelemetryStreamResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "stream_every": { "type": "integer" }, "stream_pause": { "type": "boolean" } }, "required": [ "ok", "stream_every", "stream_pause" ], "additionalProperties": true }, "example": { "ok": true, "stream_every": 4, "stream_pause": false } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "telemetry stream control: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementTelemetryStreamRequest", "type": "object", "properties": { "every": { "type": "integer" }, "pause": { "type": "boolean" } }, "required": [], "additionalProperties": true }, "example": { "every": 4, "pause": false } } } } } }, "/internal/v1/settings": { "get": { "operationId": "management_get_internal_v1_settings", "summary": "Read settings", "description": "Read settings. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. host_ip identifies the device-facing server; console_url is the configured browser origin and may use another host.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read settings response", "content": { "application/json": { "schema": { "title": "ManagementSettingsResponse", "type": "object", "properties": { "admin_username": { "type": "string" }, "trust": { "type": "array", "items": { "type": "string" } }, "host_ip": { "type": "string" }, "console_url": { "type": "string" }, "gui_cert": { "title": "ManagementSettingsResponseGui_Cert", "type": "object", "properties": { "source": { "type": "string" }, "subject": { "type": "string" }, "issuer": { "type": "string" }, "not_after": { "type": "string" }, "fingerprint_sha256": { "type": "string" } }, "required": [ "source", "subject", "issuer", "not_after", "fingerprint_sha256" ], "additionalProperties": true }, "telemetry_destination": { "title": "ManagementSettingsResponseTelemetry_Destination", "type": "object", "properties": { "endpoint": { "type": [ "string", "null" ] }, "enabled": { "type": [ "boolean", "null" ] }, "source": { "type": "string" }, "effective_endpoint": { "type": "string" }, "effective_enabled": { "type": "boolean" } }, "required": [ "endpoint", "enabled", "source", "effective_endpoint", "effective_enabled" ], "additionalProperties": true } }, "required": [ "admin_username", "trust", "host_ip", "console_url", "gui_cert", "telemetry_destination" ], "additionalProperties": true }, "example": { "admin_username": "admin", "trust": [], "host_ip": "192.0.2.10", "console_url": "https://console.example.com:8080", "gui_cert": { "source": "built-in", "subject": "CN=console.example.com", "issuer": "CN=IRIS CA", "not_after": "Sep 4 00:00:00 2027 GMT", "fingerprint_sha256": "0000000000000000000000000000000000000000000000000000000000000000" }, "telemetry_destination": { "endpoint": null, "enabled": null, "source": "env", "effective_endpoint": "https://collector.example:4318", "effective_enabled": true } } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/settings/peer-tls": { "get": { "operationId": "management_get_internal_v1_settings_peer_tls", "summary": "Read peer transfer TLS mode", "description": "Read or change process-wide BitTorrent peer TLS. Defaults to disabled. Changes persist across restarts and restart the origin seeder automatically. New device onboarding inherits the mode. Existing agents must be undeployed and device jobs finished before a change (409 otherwise); re-onboard afterward. POST requires mode and expected_mode (disabled or required); stale expected_mode returns 409. Origin status is observed separately; saved mode is not proof of fleet encryption.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Configured mode and separately observed origin state", "content": { "application/json": { "schema": { "title": "PeerTlsSettings", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "disabled", "required" ] }, "origin": { "title": "PeerTlsSettingsOrigin", "type": "object", "properties": { "active_mode": { "type": [ "string", "null" ], "enum": [ "disabled", "required", null ] }, "state": { "type": "string" } }, "required": [ "active_mode", "state" ], "additionalProperties": true }, "active_devices": { "type": "integer" }, "active_jobs": { "type": "integer" }, "can_change": { "type": "boolean" } }, "required": [ "mode", "origin", "active_devices", "active_jobs", "can_change" ], "additionalProperties": true }, "example": { "mode": "disabled", "origin": { "active_mode": "disabled", "state": "running" }, "active_devices": 0, "active_jobs": 0, "can_change": true } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "management_post_internal_v1_settings_peer_tls", "summary": "Set peer transfer TLS mode", "description": "Read or change process-wide BitTorrent peer TLS. Defaults to disabled. Changes persist across restarts and restart the origin seeder automatically. New device onboarding inherits the mode. Existing agents must be undeployed and device jobs finished before a change (409 otherwise); re-onboard afterward. POST requires mode and expected_mode (disabled or required); stale expected_mode returns 409. Origin status is observed separately; saved mode is not proof of fleet encryption.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Configured mode and separately observed origin state", "content": { "application/json": { "schema": { "title": "PeerTlsSettings", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "disabled", "required" ] }, "origin": { "title": "PeerTlsSettingsOrigin", "type": "object", "properties": { "active_mode": { "type": [ "string", "null" ], "enum": [ "disabled", "required", null ] }, "state": { "type": "string" } }, "required": [ "active_mode", "state" ], "additionalProperties": true }, "active_devices": { "type": "integer" }, "active_jobs": { "type": "integer" }, "can_change": { "type": "boolean" }, "applied": { "type": "boolean" } }, "required": [ "mode", "origin", "active_devices", "active_jobs", "can_change", "applied" ], "additionalProperties": true }, "example": { "mode": "disabled", "origin": { "active_mode": "disabled", "state": "running" }, "active_devices": 0, "active_jobs": 0, "can_change": true, "applied": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementSettingsPeerTlsRequest", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "disabled", "required" ] }, "expected_mode": { "type": "string", "enum": [ "disabled", "required" ] } }, "required": [ "mode", "expected_mode" ], "additionalProperties": false }, "example": { "mode": "required", "expected_mode": "disabled" } } } } } }, "/internal/v1/settings/password": { "post": { "operationId": "management_post_internal_v1_settings_password", "summary": "Change administrator password", "description": "Change administrator password. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Change administrator password response", "content": { "application/json": { "schema": { "title": "ManagementSettingsPasswordResponse", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementSettingsPasswordRequest", "type": "object", "properties": { "current": { "type": "string", "format": "password", "writeOnly": true }, "new": { "type": "string", "format": "password", "writeOnly": true }, "confirm": { "type": "string", "format": "password", "writeOnly": true } }, "required": [ "current", "new", "confirm" ], "additionalProperties": true }, "example": { "current": "current-password", "new": "new-password", "confirm": "new-password" } } } } } }, "/internal/v1/settings/sessions/revoke-others": { "post": { "operationId": "management_post_internal_v1_settings_sessions_revoke_others", "summary": "Revoke other sessions", "description": "Revoke other sessions. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Revoke other sessions response", "content": { "application/json": { "schema": { "title": "ManagementSettingsSessionsRevokeOthersResponse", "type": "object", "properties": { "revoked": { "type": "integer" } }, "required": [ "revoked" ], "additionalProperties": true }, "example": { "revoked": 2 } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementSettingsSessionsRevokeOthersRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/internal/v1/settings/setup-status": { "get": { "operationId": "management_get_internal_v1_settings_setup_status", "summary": "Read setup status", "description": "Read setup status. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read setup status response", "content": { "application/json": { "schema": { "title": "ManagementSettingsSetupStatusResponse", "type": "object", "properties": { "admin": { "title": "ManagementSettingsSetupStatusResponseAdmin", "type": "object", "properties": { "state": { "type": "string" }, "username": { "type": "string" } }, "required": [ "state", "username" ], "additionalProperties": true }, "telemetry": { "title": "ManagementSettingsSetupStatusResponseTelemetry", "type": "object", "properties": { "state": { "type": "string" }, "source": { "type": "string" }, "enabled": { "type": "boolean" }, "endpoint": { "type": "string", "format": "uri" } }, "required": [ "state", "source", "enabled", "endpoint" ], "additionalProperties": true }, "packages": { "title": "ManagementSettingsSetupStatusResponsePackages", "type": "object", "properties": { "state": { "type": "string", "enum": [ "ok", "absent", "unknown", "stale" ] }, "reference_fingerprint": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "title": "ManagementSettingsSetupStatusResponsePackagesItemsItem", "type": "object", "properties": { "name": { "type": "string" }, "state": { "type": "string", "enum": [ "ok", "absent", "unknown", "stale" ] }, "fingerprint": { "type": [ "string", "null" ], "description": "Null for deployment-neutral packages; runtime trust is reported by packages.reference_fingerprint." }, "built_at": { "type": [ "integer", "null" ], "description": "Artifact file modification time as Unix seconds; the field name does not attest the original package build time." }, "detail": { "type": "string" }, "remedy": { "type": "string" }, "provenance": { "type": [ "object", "null" ], "description": "Adjacent sidecar metadata bound to readable wrapper bytes. This check does not authenticate the sidecar or verify native signatures.", "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "properties": { "canonical_index_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "minLength": 71, "maxLength": 71 }, "canonical_archive_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "minLength": 64, "maxLength": 64 }, "canonical_source_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "minLength": 64, "maxLength": 64, "description": "Version 1 rooted build-context digest." } }, "required": [ "canonical_index_digest", "canonical_archive_sha256", "canonical_source_sha256" ] }, { "type": "object", "additionalProperties": false, "properties": { "canonical_index_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "minLength": 71, "maxLength": 71 }, "canonical_archive_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "minLength": 64, "maxLength": 64 }, "format": { "type": "string", "const": "iris-device-wrapper-v2" }, "canonical_neutral_source_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "minLength": 64, "maxLength": 64, "description": "Neutral build-context digest, not the version 1 rooted source digest." }, "canonical_finalization_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "minLength": 64, "maxLength": 64, "description": "Digest of the deployment-specific trust finalization record." } }, "required": [ "canonical_index_digest", "canonical_archive_sha256", "format", "canonical_neutral_source_sha256", "canonical_finalization_sha256" ] } ] }, "reason": { "type": "string" } }, "required": [ "name", "state", "fingerprint", "built_at", "remedy", "provenance" ], "additionalProperties": false } }, "remedy": { "type": "string" }, "reason": { "type": "string", "enum": [ "served-cert-unavailable", "distributed-cert-unavailable", "served-vs-distributed-mismatch" ] } }, "required": [ "state", "reference_fingerprint", "items", "remedy" ], "additionalProperties": true }, "image_verification": { "title": "ManagementSettingsSetupStatusResponseImage_Verification", "type": "object", "properties": { "state": { "type": "string" } }, "required": [ "state" ], "additionalProperties": true } }, "required": [ "admin", "telemetry", "packages", "image_verification" ], "additionalProperties": true }, "example": { "admin": { "state": "ok", "username": "admin" }, "telemetry": { "state": "ok", "source": "env", "enabled": true, "endpoint": "https://collector.example:4318" }, "packages": { "state": "ok", "reference_fingerprint": "00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00", "items": [ { "name": "iris-amd64.tar", "state": "ok", "fingerprint": null, "built_at": 1788470400, "detail": "Package bytes match build provenance", "remedy": "tools/provision-iox-packages.sh", "provenance": { "canonical_index_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "canonical_archive_sha256": "1111111111111111111111111111111111111111111111111111111111111111", "canonical_source_sha256": "2222222222222222222222222222222222222222222222222222222222222222" } }, { "name": "iris-arm64.tar", "state": "ok", "fingerprint": null, "built_at": 1788470400, "detail": "Package bytes match build provenance", "remedy": "tools/provision-iox-packages.sh", "provenance": { "canonical_index_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "canonical_archive_sha256": "1111111111111111111111111111111111111111111111111111111111111111", "canonical_source_sha256": "2222222222222222222222222222222222222222222222222222222222222222" } }, { "name": "iris-xr.rpm", "state": "ok", "fingerprint": null, "built_at": 1788470400, "detail": "Package bytes match build provenance", "remedy": "tools/build-xr-package.sh --out artifacts/", "provenance": { "canonical_index_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "canonical_archive_sha256": "1111111111111111111111111111111111111111111111111111111111111111", "canonical_source_sha256": "2222222222222222222222222222222222222222222222222222222222222222" } }, { "name": "iris-agent.tgz", "state": "ok", "fingerprint": null, "built_at": 1788470400, "provenance": null, "reason": "ready", "detail": "Served Guest Shell files and embedded instruction trust match current startup provisioning.", "remedy": "Rebuild the server image and restart after correcting the provisioning error." } ], "remedy": "tools/provision-iox-packages.sh" }, "image_verification": { "state": "ok" } } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/settings/certificates": { "get": { "operationId": "management_get_internal_v1_settings_certificates", "summary": "Inspect server certificate validity", "description": "Inspect server certificate validity. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Inspect server certificate validity response", "content": { "application/json": { "schema": { "title": "ManagementSettingsCertificatesResponse", "type": "object", "properties": { "observed_at": { "type": "integer" }, "scope": { "type": "string" }, "items": { "type": "array", "items": { "title": "ManagementSettingsCertificatesResponseItemsItem", "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "certificate", "public-key" ] }, "state": { "type": "string", "enum": [ "unknown", "within-validity", "not-yet-valid", "expired", "signing-refused", "renewal-due", "public-key-present" ] }, "source": { "type": "string" }, "fingerprint_sha256": { "type": [ "string", "null" ] }, "valid_from": { "type": [ "integer", "null" ] }, "expires_at": { "type": [ "integer", "null" ] }, "renew_at": { "type": [ "integer", "null" ] }, "refuse_at": { "type": [ "integer", "null" ] }, "impact": { "type": "string" } }, "required": [ "id", "label", "kind", "state", "source", "fingerprint_sha256", "valid_from", "expires_at", "renew_at", "refuse_at", "impact" ], "additionalProperties": true } }, "custody": { "type": [ "object", "null" ], "additionalProperties": true }, "note": { "type": "string" } }, "required": [ "observed_at", "scope", "items", "custody", "note" ], "additionalProperties": true }, "example": { "observed_at": 1788470400, "scope": "server-certificate-files", "items": [ { "id": "instruction-signer", "label": "Instruction signing certificate", "kind": "certificate", "state": "renewal-due", "source": "server-file", "fingerprint_sha256": "0000000000000000000000000000000000000000000000000000000000000000", "valid_from": 1787000000, "expires_at": 1789592000, "renew_at": 1788296000, "refuse_at": 1788987200, "impact": "Renew with offline root approval." } ], "custody": null, "note": "Validity dates do not prove trust, key availability or the certificate loaded by a listener." } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/settings/service-credentials": { "get": { "operationId": "management_get_internal_v1_settings_service_credentials", "summary": "Read metrics and collector credential rotation", "description": "Read metrics and collector credential rotation. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read metrics and collector credential rotation response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "object", "properties": { "family": { "enum": [ "metrics-token", "collector-headers" ] }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "enum": [ "deployment-managed", "awaiting-verification", "completed", "reverted" ] }, "previous_retained": { "type": "boolean" }, "started_at": { "type": [ "integer", "null" ] }, "observed_at": { "type": [ "integer", "null" ] }, "endpoint": { "type": [ "string", "null" ] } }, "required": [ "family", "request_id", "state", "previous_retained", "started_at", "observed_at", "endpoint" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, "example": { "items": [ { "family": "metrics-token", "request_id": null, "state": "deployment-managed", "previous_retained": false, "started_at": null, "observed_at": null, "endpoint": null }, { "family": "collector-headers", "request_id": null, "state": "deployment-managed", "previous_retained": false, "started_at": null, "observed_at": null, "endpoint": null } ] } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "management_post_internal_v1_settings_service_credentials", "summary": "Replace or retire metrics and collector credentials", "description": "Replace or retire metrics and collector credentials. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Replace or retire metrics and collector credentials response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "object", "properties": { "family": { "enum": [ "metrics-token", "collector-headers" ] }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "enum": [ "deployment-managed", "awaiting-verification", "completed", "reverted" ] }, "previous_retained": { "type": "boolean" }, "started_at": { "type": [ "integer", "null" ] }, "observed_at": { "type": [ "integer", "null" ] }, "endpoint": { "type": [ "string", "null" ] } }, "required": [ "family", "request_id", "state", "previous_retained", "started_at", "observed_at", "endpoint" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, "example": { "items": [ { "family": "metrics-token", "request_id": null, "state": "deployment-managed", "previous_retained": false, "started_at": null, "observed_at": null, "endpoint": null }, { "family": "collector-headers", "request_id": null, "state": "deployment-managed", "previous_retained": false, "started_at": null, "observed_at": null, "endpoint": null } ] } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "const": "replace" }, "family": { "const": "metrics-token" }, "request_id": { "type": "string", "format": "uuid" }, "confirm": { "const": true }, "token": { "type": "string", "minLength": 32, "maxLength": 256, "writeOnly": true } }, "required": [ "action", "family", "request_id", "confirm", "token" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "const": "replace" }, "family": { "const": "collector-headers" }, "request_id": { "type": "string", "format": "uuid" }, "confirm": { "const": true }, "headers": { "type": "object", "minProperties": 1, "maxProperties": 16, "writeOnly": true, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "endpoint": { "type": "string", "maxLength": 2048, "pattern": "^https://" } }, "required": [ "action", "family", "request_id", "confirm", "headers", "endpoint" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "enum": [ "retire", "revert" ] }, "family": { "enum": [ "metrics-token", "collector-headers" ] }, "request_id": { "type": "string", "format": "uuid" }, "confirm": { "const": true } }, "required": [ "action", "family", "request_id", "confirm" ], "additionalProperties": false } ] }, "example": { "action": "replace", "family": "metrics-token", "request_id": "00000000-0000-0000-0000-000000000001", "confirm": true, "token": "example-new-scrape-token-0123456789" } } } } } }, "/internal/v1/settings/certificates/browser/rotation": { "get": { "operationId": "management_get_internal_v1_settings_certificates_browser_rotation", "summary": "Read browser TLS rotation", "description": "Read browser TLS rotation. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read browser TLS rotation response", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "enum": [ "idle", "awaiting-approval", "approved", "committing", "published", "cancelled" ] }, "names": { "type": "array", "items": { "type": "string" } }, "mode": { "enum": [ null, "ca", "self-signed" ] }, "csr": { "type": [ "string", "null" ] }, "certificate": { "type": [ "string", "null" ] }, "created_at": { "type": [ "integer", "null" ] }, "fingerprint_sha256": { "type": [ "string", "null" ] } }, "required": [ "request_id", "state", "names", "mode", "csr", "certificate", "created_at", "fingerprint_sha256" ], "additionalProperties": false }, "example": { "request_id": null, "state": "idle", "names": [], "mode": null, "csr": null, "certificate": null, "created_at": null, "fingerprint_sha256": null } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "management_post_internal_v1_settings_certificates_browser_rotation", "summary": "Prepare, approve or apply browser TLS rotation", "description": "Prepare, approve or apply browser TLS rotation. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Prepare, approve or apply browser TLS rotation response", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "enum": [ "idle", "awaiting-approval", "approved", "committing", "published", "cancelled" ] }, "names": { "type": "array", "items": { "type": "string" } }, "mode": { "enum": [ null, "ca", "self-signed" ] }, "csr": { "type": [ "string", "null" ] }, "certificate": { "type": [ "string", "null" ] }, "created_at": { "type": [ "integer", "null" ] }, "fingerprint_sha256": { "type": [ "string", "null" ] }, "applied": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "gui_cert": { "type": "object", "properties": { "source": { "type": "string" }, "subject": { "type": "string" }, "issuer": { "type": "string" }, "not_after": { "type": "string" }, "fingerprint_sha256": { "type": "string" } }, "required": [ "source", "subject", "issuer", "not_after", "fingerprint_sha256" ], "additionalProperties": false } }, "required": [ "request_id", "state", "names", "mode", "csr", "certificate", "created_at", "fingerprint_sha256" ], "additionalProperties": false }, "example": { "request_id": null, "state": "idle", "names": [], "mode": null, "csr": null, "certificate": null, "created_at": null, "fingerprint_sha256": null } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "const": "prepare" }, "request_id": { "type": "string", "format": "uuid" }, "names": { "type": "array", "minItems": 1, "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 253 } }, "mode": { "enum": [ "ca", "self-signed" ] } }, "required": [ "action", "request_id", "names", "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "const": "approve" }, "request_id": { "type": "string", "format": "uuid" }, "certificate": { "type": "string", "maxLength": 65536 } }, "required": [ "action", "request_id", "certificate" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "const": "apply" }, "request_id": { "type": "string", "format": "uuid" }, "confirm": { "const": true } }, "required": [ "action", "request_id", "confirm" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "const": "cancel" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "action", "request_id" ], "additionalProperties": false } ] }, "example": { "action": "prepare", "request_id": "00000000-0000-0000-0000-000000000001", "names": [ "console.example.com" ], "mode": "ca" } } } } } }, "/internal/v1/settings/backups": { "get": { "operationId": "management_get_internal_v1_settings_backups", "summary": "Read deployment backup worker status", "description": "Read deployment backup worker status. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "retention_request_id", "in": "query", "required": false, "description": "Observe the exact history-retirement or archive-deletion request after an uncertain response", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read deployment backup worker status response", "content": { "application/json": { "schema": { "title": "ManagementSettingsBackupsResponse", "type": "object", "properties": { "available": { "type": "boolean" }, "target": { "type": "string" }, "storage": { "type": "string" }, "can_verify": { "type": "boolean" }, "can_extract": { "type": "boolean" }, "can_restore": { "type": "boolean" }, "jobs": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "action", "backup_id", "state", "started_at", "detail" ], "properties": { "id": { "type": "string" }, "backup_id": { "type": "string" }, "action": { "enum": [ "backup", "verify", "extract", "restore" ] }, "state": { "enum": [ "running", "recovery-required", "captured", "failed", "verified-files", "verified-isolated-files", "restored", "refused" ] }, "started_at": { "type": "integer" }, "finished_at": { "type": "integer" }, "detail": { "type": "string" }, "proof": { "type": [ "object", "null" ], "additionalProperties": true } } } }, "note": { "type": "string" }, "retention": { "type": "object", "properties": { "schema": { "const": 1 }, "revision": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "busy": { "type": "boolean" }, "inventory_available": { "type": "boolean", "description": "False when unrecognized archive storage prevents a complete read-only inventory. Recovery job evidence remains available." }, "storage_problem": { "type": [ "string", "null" ], "maxLength": 1024 }, "recoverable_job_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The sole interrupted operation that can be explicitly recovered; null while another maintenance action blocks it." }, "capacity": { "type": "object", "properties": { "history_used": { "type": "integer", "minimum": 0, "maximum": 100 }, "history_limit": { "const": 100 }, "backup_used": { "type": [ "integer", "null" ], "minimum": 0 }, "backup_limit": { "const": 20 }, "protected_upgrade_used": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "history_used", "history_limit", "backup_used", "backup_limit" ], "additionalProperties": false }, "jobs": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "state": { "type": "string" }, "backup_id": { "type": [ "string", "null" ], "format": "uuid" }, "family": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "integer", "null" ] }, "retire_allowed": { "type": "boolean" }, "retire_reason": { "type": "string" } }, "required": [ "id", "action", "state", "backup_id", "family", "finished_at", "retire_allowed", "retire_reason" ], "additionalProperties": false } }, "backups": { "type": "array", "items": { "type": "object", "properties": { "backup_id": { "type": "string", "format": "uuid" }, "created_at": { "type": [ "integer", "null" ] }, "delete_allowed": { "type": "boolean" }, "delete_reason": { "type": "string" } }, "required": [ "backup_id", "created_at", "delete_allowed", "delete_reason" ], "additionalProperties": false } }, "protected_upgrade_backups": { "type": "array", "items": { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid" }, "attempt": { "type": "integer", "minimum": 1, "maximum": 3 }, "phase": { "enum": [ "building", "prepared", "fencing", "backing-up", "stopped", "publishing", "published", "starting", "verifying", "worker", "finishing", "upgraded", "cancelled", "recovery-required" ] }, "deployment_archive": { "type": "boolean" }, "recovery_archive": { "type": "boolean" } }, "required": [ "operation_id", "attempt", "phase", "deployment_archive", "recovery_archive" ], "additionalProperties": false } }, "operation": { "oneOf": [ { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "action": { "enum": [ "retire-history", "delete-backup" ] }, "state": { "enum": [ "running", "completed", "recovery-required" ] }, "retired_count": { "type": "integer", "minimum": 0, "maximum": 100 }, "backup_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "request_id", "action", "state", "retired_count", "backup_id" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "schema", "revision", "busy", "capacity", "jobs", "backups", "operation" ], "additionalProperties": false, "dependentRequired": { "inventory_available": [ "storage_problem" ], "storage_problem": [ "inventory_available" ] }, "allOf": [ { "if": { "properties": { "inventory_available": { "const": false } }, "required": [ "inventory_available" ] }, "then": { "required": [ "protected_upgrade_backups" ], "properties": { "storage_problem": { "type": "string", "minLength": 1 }, "capacity": { "required": [ "protected_upgrade_used" ], "properties": { "backup_used": { "type": "null" }, "protected_upgrade_used": { "type": "null" } } }, "backups": { "maxItems": 0 }, "protected_upgrade_backups": { "maxItems": 0 }, "jobs": { "items": { "properties": { "retire_allowed": { "const": false } } } } } }, "else": { "properties": { "storage_problem": { "type": "null" }, "capacity": { "properties": { "backup_used": { "type": "integer" }, "protected_upgrade_used": { "type": "integer" } } } } } } ] }, "can_recover_backup": { "type": "boolean", "description": "Whether this managed worker supports recovery of its recorded interrupted backups." }, "restore_scope": { "type": "string", "enum": [ "same-deployment-same-security-generation" ] } }, "required": [ "available", "target", "storage", "can_verify", "can_extract", "can_restore", "jobs", "note" ], "additionalProperties": true }, "example": { "available": false, "target": "unavailable", "storage": "unavailable", "can_verify": false, "can_extract": false, "can_restore": false, "jobs": [], "note": "Configure the lifecycle worker on the installer host." } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "management_post_internal_v1_settings_backups", "summary": "Request backup, verification, extraction, restore or recovery, history retirement or exact archive deletion", "description": "Request backup, verification, extraction, restore or recovery, history retirement or exact archive deletion. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Request backup, verification, extraction, restore or recovery, history retirement or exact archive deletion response", "content": { "application/json": { "schema": { "oneOf": [ { "title": "ManagementSettingsBackupsResponse", "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ], "additionalProperties": true }, { "type": "object", "properties": { "retention_operation": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "action": { "enum": [ "retire-history", "delete-backup" ] }, "state": { "enum": [ "running", "completed", "recovery-required" ] }, "retired_count": { "type": "integer", "minimum": 0, "maximum": 100 }, "backup_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "request_id", "action", "state", "retired_count", "backup_id" ], "additionalProperties": false } }, "required": [ "retention_operation" ], "additionalProperties": false } ] }, "example": { "job_id": "00000000-0000-0000-0000-000000000001" } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "action", "allow_downtime", "request_id" ], "properties": { "action": { "const": "backup" }, "allow_downtime": { "const": true }, "request_id": { "type": "string", "pattern": "^[0-9a-f-]{36}$" } } }, { "type": "object", "properties": { "action": { "const": "recover-backup" }, "request_id": { "type": "string", "format": "uuid" }, "backup_id": { "type": "string", "format": "uuid" }, "allow_downtime": { "const": true } }, "required": [ "action", "request_id", "backup_id", "allow_downtime" ], "additionalProperties": false }, { "type": "object", "additionalProperties": false, "required": [ "action", "backup_id", "request_id" ], "properties": { "action": { "enum": [ "verify", "extract" ] }, "backup_id": { "type": "string", "pattern": "^[0-9a-f-]{36}$" }, "request_id": { "type": "string", "pattern": "^[0-9a-f-]{36}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "action", "backup_id", "request_id", "allow_downtime", "confirm_restore" ], "properties": { "action": { "enum": [ "restore", "recover-restore" ] }, "backup_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "allow_downtime": { "const": true }, "confirm_restore": { "const": true } } }, { "type": "object", "properties": { "action": { "const": "retire-history" }, "request_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "job_ids": { "type": "array", "minItems": 1, "maxItems": 25, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } } }, "required": [ "action", "request_id", "expected_revision", "job_ids" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "enum": [ "delete-backup", "resume-delete" ] }, "request_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "backup_id": { "type": "string", "format": "uuid" }, "confirm_delete": { "const": true } }, "required": [ "action", "request_id", "expected_revision", "backup_id", "confirm_delete" ], "additionalProperties": false } ] }, "example": { "action": "backup", "allow_downtime": true, "request_id": "00000000-0000-0000-0000-000000000001" } } } } } }, "/internal/v1/settings/deployment-rotation": { "get": { "operationId": "management_get_internal_v1_settings_deployment_rotation", "summary": "Read deployment credential maintenance evidence", "description": "Read deployment credential maintenance evidence. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read deployment credential maintenance evidence response", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "target": { "enum": [ "single-docker", "split-docker", "kubernetes", "unavailable" ] }, "can_rotate": { "type": "boolean" }, "note": { "type": "string" }, "families": { "type": "array", "items": { "enum": [ "management-tls", "device-tls", "peer-ca", "instruction-roots", "age-identity", "age-recovery", "seeder-announce" ] } }, "jobs": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "action", "family", "state", "started_at", "detail", "proof" ], "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "const": "rotate" }, "family": { "type": "string" }, "state": { "type": "string" }, "started_at": { "type": "integer" }, "finished_at": { "type": "integer" }, "detail": { "type": "string" }, "proof": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "management_https": { "const": "verified" }, "certificate_sha256": { "type": "string" }, "console_consumers": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "pod_uid": { "type": "string" }, "certificate_sha256": { "type": "string" }, "management_https": { "const": "verified" } }, "required": [ "pod_uid", "certificate_sha256", "management_https" ], "additionalProperties": false } }, "dedicated_management_key": { "const": "verified" }, "age_files": { "type": "integer" }, "service_recipient": { "type": "string" }, "recovery_recipient": { "type": "string" }, "independent_decryption": { "const": "verified" }, "seeded_torrents": { "type": "integer" }, "credential_changed": { "const": true }, "isolated_tracker_proof": { "const": "verified" }, "restarted_tracker_proof": { "const": "verified" }, "family": { "enum": [ "device-tls", "peer-ca", "instruction-roots" ] }, "request_id": { "type": "string", "format": "uuid" }, "packages_verified": { "const": true }, "device_consumers": { "const": "re-onboarding-required" }, "catalog_tls_sha256": { "type": "string" }, "peer_ca_sha256": { "type": "string" }, "origin_mode": { "enum": [ "required", "disabled" ] }, "root_sha256": { "type": "object", "additionalProperties": { "type": "string" } }, "keylist_seq": { "type": "integer" } } } } } } }, "required": [ "available", "target", "can_rotate", "note", "families", "jobs" ], "additionalProperties": false }, "example": { "available": false, "target": "unavailable", "can_rotate": false, "families": [], "jobs": [], "note": "Configure deployment maintenance and recovery access." } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "management_post_internal_v1_settings_deployment_rotation", "summary": "Request verified-backup credential maintenance", "description": "Request verified-backup credential maintenance. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Request verified-backup credential maintenance response", "content": { "application/json": { "schema": { "title": "ManagementSettingsDeploymentRotationResponse", "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ], "additionalProperties": true }, "example": { "job_id": "00000000-0000-0000-0000-000000000001" } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "enum": [ "rotate", "recover-rotation" ] }, "allow_downtime": { "const": true }, "request_id": { "type": "string", "format": "uuid" }, "family": { "enum": [ "management-tls", "device-tls", "peer-ca", "instruction-roots", "age-identity", "age-recovery", "seeder-announce" ] } }, "required": [ "action", "allow_downtime", "request_id", "family" ], "additionalProperties": false }, "example": { "action": "rotate", "allow_downtime": true, "request_id": "00000000-0000-0000-0000-000000000001", "family": "management-tls" } } } } } }, "/internal/v1/settings/trust-rotation": { "get": { "operationId": "management_get_internal_v1_settings_trust_rotation", "summary": "Read public deployment trust approvals", "description": "Read public deployment trust approvals. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read public deployment trust approvals response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": "object", "properties": { "family": { "enum": [ "device-tls", "peer-ca", "instruction-roots" ] }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "enum": [ "idle", "awaiting-approval", "approved", "committing", "published", "cancelled" ] }, "created_at": { "type": [ "integer", "null" ] }, "names": { "type": "array", "items": { "type": "string" } }, "mode": { "type": [ "string", "null" ] }, "csr": { "type": [ "string", "null" ] }, "certificate": { "type": [ "string", "null" ] }, "fingerprint_sha256": { "type": [ "string", "null" ] }, "roots": { "type": "object", "additionalProperties": { "type": "string" } }, "online_public_key": { "type": [ "string", "null" ] }, "keylist_payload": { "type": [ "string", "null" ] }, "keylist_signer": { "type": [ "string", "null" ] }, "requires_reonboarding": { "type": "boolean" }, "requires_package_rebuild": { "type": "boolean" }, "attestation_request_id": { "type": [ "string", "null" ], "format": "uuid" }, "attestation_root_id": { "type": [ "string", "null" ] }, "attested_root_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "family", "request_id", "state", "created_at", "names", "mode", "csr", "certificate", "fingerprint_sha256", "roots", "online_public_key", "keylist_payload", "keylist_signer", "requires_reonboarding", "requires_package_rebuild", "attestation_request_id", "attestation_root_id", "attested_root_ids" ], "additionalProperties": false } }, "drain": { "type": "object", "properties": { "ready": { "type": "boolean" }, "blocked_device_ids": { "type": "array", "items": { "type": "string" } }, "removed_device_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "ready", "blocked_device_ids", "removed_device_ids" ], "additionalProperties": false } }, "required": [ "items", "drain" ], "additionalProperties": false }, "example": { "items": [ { "family": "device-tls", "request_id": null, "state": "idle", "created_at": null, "names": [], "mode": null, "csr": null, "certificate": null, "fingerprint_sha256": null, "roots": {}, "online_public_key": null, "keylist_payload": null, "keylist_signer": null, "requires_reonboarding": true, "requires_package_rebuild": false, "attested_root_ids": [], "attestation_request_id": null, "attestation_root_id": null }, { "family": "peer-ca", "request_id": null, "state": "idle", "created_at": null, "names": [], "mode": null, "csr": null, "certificate": null, "fingerprint_sha256": null, "roots": {}, "online_public_key": null, "keylist_payload": null, "keylist_signer": null, "requires_reonboarding": true, "requires_package_rebuild": false, "attested_root_ids": [], "attestation_request_id": null, "attestation_root_id": null }, { "family": "instruction-roots", "request_id": null, "state": "idle", "created_at": null, "names": [], "mode": null, "csr": null, "certificate": null, "fingerprint_sha256": null, "roots": {}, "online_public_key": null, "keylist_payload": null, "keylist_signer": null, "requires_reonboarding": true, "requires_package_rebuild": true, "attested_root_ids": [], "attestation_request_id": null, "attestation_root_id": null } ], "drain": { "ready": true, "blocked_device_ids": [], "removed_device_ids": [] } } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "management_post_internal_v1_settings_trust_rotation", "summary": "Prepare or approve deployment trust without publishing", "description": "Prepare or approve deployment trust without publishing. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Prepare or approve deployment trust without publishing response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "family": { "enum": [ "device-tls", "peer-ca", "instruction-roots" ] }, "request_id": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "enum": [ "idle", "awaiting-approval", "approved", "committing", "published", "cancelled" ] }, "created_at": { "type": [ "integer", "null" ] }, "names": { "type": "array", "items": { "type": "string" } }, "mode": { "type": [ "string", "null" ] }, "csr": { "type": [ "string", "null" ] }, "certificate": { "type": [ "string", "null" ] }, "fingerprint_sha256": { "type": [ "string", "null" ] }, "roots": { "type": "object", "additionalProperties": { "type": "string" } }, "online_public_key": { "type": [ "string", "null" ] }, "keylist_payload": { "type": [ "string", "null" ] }, "keylist_signer": { "type": [ "string", "null" ] }, "requires_reonboarding": { "type": "boolean" }, "requires_package_rebuild": { "type": "boolean" }, "attestation_request_id": { "type": [ "string", "null" ], "format": "uuid" }, "attestation_root_id": { "type": [ "string", "null" ] }, "attested_root_ids": { "type": "array", "items": { "type": "string" } }, "attestation_applied": { "const": true, "description": "Present only after the signed current-root attestation was installed and verified." } }, "required": [ "family", "request_id", "state", "created_at", "names", "mode", "csr", "certificate", "fingerprint_sha256", "roots", "online_public_key", "keylist_payload", "keylist_signer", "requires_reonboarding", "requires_package_rebuild", "attestation_request_id", "attestation_root_id", "attested_root_ids" ], "additionalProperties": false }, { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "root_id": { "type": "string" }, "payload": { "type": "string" } }, "required": [ "request_id", "root_id", "payload" ], "additionalProperties": false } ] }, "example": { "family": "peer-ca", "request_id": null, "state": "idle", "created_at": null, "names": [], "mode": null, "csr": null, "certificate": null, "fingerprint_sha256": null, "roots": {}, "online_public_key": null, "keylist_payload": null, "keylist_signer": null, "requires_reonboarding": true, "requires_package_rebuild": false, "attested_root_ids": [], "attestation_request_id": null, "attestation_root_id": null } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "family": { "const": "device-tls" }, "action": { "const": "prepare" }, "request_id": { "type": "string", "format": "uuid" }, "names": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "maxLength": 253 } }, "mode": { "enum": [ "ca", "self-signed" ] } }, "required": [ "family", "action", "request_id", "names", "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "peer-ca" }, "action": { "const": "prepare" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "family", "action", "request_id" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "instruction-roots" }, "action": { "const": "prepare" }, "request_id": { "type": "string", "format": "uuid" }, "roots": { "type": "object", "minProperties": 2, "maxProperties": 2, "additionalProperties": { "type": "string", "maxLength": 4096 } }, "keylist_signer": { "type": "string", "maxLength": 64 } }, "required": [ "family", "action", "request_id", "roots", "keylist_signer" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "device-tls" }, "action": { "const": "approve" }, "request_id": { "type": "string", "format": "uuid" }, "certificate": { "type": "string", "maxLength": 65536 } }, "required": [ "family", "action", "request_id", "certificate" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "instruction-roots" }, "action": { "const": "approve" }, "request_id": { "type": "string", "format": "uuid" }, "certificate": { "type": "string", "maxLength": 65536 }, "keylist": { "type": "string", "maxLength": 174764 } }, "required": [ "family", "action", "request_id", "certificate", "keylist" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "instruction-roots" }, "action": { "const": "attestation-request" }, "request_id": { "type": "string", "format": "uuid" }, "root_id": { "type": "string", "maxLength": 64 } }, "required": [ "family", "action", "request_id", "root_id" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "instruction-roots" }, "action": { "const": "attestation-apply" }, "request_id": { "type": "string", "format": "uuid" }, "root_id": { "type": "string", "maxLength": 64 }, "keylist": { "type": "string", "maxLength": 174764 } }, "required": [ "family", "action", "request_id", "root_id", "keylist" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "device-tls" }, "action": { "const": "cancel" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "family", "action", "request_id" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "peer-ca" }, "action": { "const": "cancel" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "family", "action", "request_id" ], "additionalProperties": false }, { "type": "object", "properties": { "family": { "const": "instruction-roots" }, "action": { "const": "cancel" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "family", "action", "request_id" ], "additionalProperties": false } ] }, "example": { "action": "prepare", "family": "peer-ca", "request_id": "00000000-0000-0000-0000-000000000001" } } } } } }, "/internal/v1/settings/certificates/instruction/request": { "post": { "operationId": "management_post_internal_v1_settings_certificates_instruction_request", "summary": "Prepare public instruction certificate renewal", "description": "Prepare public instruction certificate renewal. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Prepare public instruction certificate renewal response", "content": { "application/json": { "schema": { "title": "ManagementSettingsCertificatesInstructionRequestResponse", "type": "object", "properties": { "public_key": { "type": "string" }, "public_key_sha256": { "type": "string" }, "certificate_sha256": { "type": "string" } }, "required": [ "public_key", "public_key_sha256", "certificate_sha256" ], "additionalProperties": true }, "example": { "public_key": "ssh-ed25519 ...", "public_key_sha256": "0000000000000000000000000000000000000000000000000000000000000000", "certificate_sha256": "1111111111111111111111111111111111111111111111111111111111111111" } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementSettingsCertificatesInstructionRequestRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } } } }, "/internal/v1/settings/certificates/instruction/renew": { "post": { "operationId": "management_post_internal_v1_settings_certificates_instruction_renew", "summary": "Renew the existing instruction signing certificate", "description": "Renew the existing instruction signing certificate. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Renew the existing instruction signing certificate response", "content": { "application/json": { "schema": { "title": "ManagementSettingsCertificatesInstructionRenewResponse", "type": "object", "properties": { "applied": { "type": "boolean" }, "expires_at": { "type": "integer" }, "refuse_at": { "type": "integer" }, "status_refreshed": { "type": "boolean" } }, "required": [ "applied", "expires_at", "refuse_at", "status_refreshed" ], "additionalProperties": true }, "example": { "applied": true, "expires_at": 1789592000, "refuse_at": 1788987200, "status_refreshed": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementSettingsCertificatesInstructionRenewRequest", "type": "object", "properties": { "certificate": { "type": "string", "maxLength": 65536 }, "public_key_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "certificate_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "certificate", "public_key_sha256", "certificate_sha256" ], "additionalProperties": false }, "example": { "certificate": "ssh-ed25519-cert-v01@openssh.com ...", "public_key_sha256": "0000000000000000000000000000000000000000000000000000000000000000", "certificate_sha256": "1111111111111111111111111111111111111111111111111111111111111111" } } } } } }, "/internal/v1/settings/certificates/instruction/rotation": { "get": { "operationId": "management_get_internal_v1_settings_certificates_instruction_rotation", "summary": "Inspect online signer rotation", "description": "Inspect online signer rotation. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Inspect online signer rotation response", "content": { "application/json": { "schema": { "title": "ManagementSettingsCertificatesInstructionRotationResponse", "type": "object", "properties": { "state": { "enum": [ "idle", "awaiting-approval", "committing", "retirement-pending", "retiring", "completed", "cancelled" ] }, "request_id": { "type": [ "string", "null" ] }, "previous_public_key": { "type": [ "string", "null" ] }, "public_key": { "type": [ "string", "null" ] }, "previous_sha256": { "type": [ "string", "null" ] }, "replacement_sha256": { "type": [ "string", "null" ] }, "created_at": { "type": [ "integer", "null" ] }, "activated_at": { "type": [ "integer", "null" ] }, "retired_keylist_seq": { "type": [ "integer", "null" ] }, "root_ids": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } }, "required": [ "state", "request_id", "previous_public_key", "public_key", "previous_sha256", "replacement_sha256", "created_at", "activated_at", "retired_keylist_seq", "root_ids", "note" ], "additionalProperties": false }, "example": { "state": "idle", "request_id": null, "previous_public_key": null, "public_key": null, "previous_sha256": null, "replacement_sha256": null, "created_at": null, "activated_at": null, "retired_keylist_seq": null, "root_ids": [ "root-a", "root-b" ], "note": "Server-side evidence; confirm device acceptance separately." } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "management_post_internal_v1_settings_certificates_instruction_rotation", "summary": "Prepare, activate or retire an online signer", "description": "Prepare, activate or retire an online signer. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Prepare, activate or retire an online signer response", "content": { "application/json": { "schema": { "oneOf": [ { "title": "ManagementSettingsCertificatesInstructionRotationResponse", "type": "object", "properties": { "state": { "enum": [ "idle", "awaiting-approval", "committing", "retirement-pending", "retiring", "completed", "cancelled" ] }, "request_id": { "type": [ "string", "null" ] }, "previous_public_key": { "type": [ "string", "null" ] }, "public_key": { "type": [ "string", "null" ] }, "previous_sha256": { "type": [ "string", "null" ] }, "replacement_sha256": { "type": [ "string", "null" ] }, "created_at": { "type": [ "integer", "null" ] }, "activated_at": { "type": [ "integer", "null" ] }, "retired_keylist_seq": { "type": [ "integer", "null" ] }, "root_ids": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } }, "required": [ "state", "request_id", "previous_public_key", "public_key", "previous_sha256", "replacement_sha256", "created_at", "activated_at", "retired_keylist_seq", "root_ids", "note" ], "additionalProperties": false }, { "type": "object", "additionalProperties": false, "required": [ "request_id", "payload", "root_id" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "payload": { "type": "string" }, "root_id": { "type": "string" } } } ] }, "example": { "state": "idle", "request_id": null, "previous_public_key": null, "public_key": null, "previous_sha256": null, "replacement_sha256": null, "created_at": null, "activated_at": null, "retired_keylist_seq": null, "root_ids": [ "root-a", "root-b" ], "note": "Server-side evidence; confirm device acceptance separately." } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "action": { "const": "prepare" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "action", "request_id" ] }, { "type": "object", "additionalProperties": false, "properties": { "action": { "const": "cancel" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "action", "request_id" ] }, { "type": "object", "additionalProperties": false, "properties": { "action": { "const": "activate" }, "request_id": { "type": "string", "format": "uuid" }, "certificate": { "type": "string", "maxLength": 65536 }, "confirm": { "const": true } }, "required": [ "action", "request_id", "certificate", "confirm" ] }, { "type": "object", "additionalProperties": false, "properties": { "action": { "const": "retirement-request" }, "request_id": { "type": "string", "format": "uuid" }, "root_id": { "type": "string", "maxLength": 64 } }, "required": [ "action", "request_id", "root_id" ] }, { "type": "object", "additionalProperties": false, "properties": { "action": { "const": "retire" }, "request_id": { "type": "string", "format": "uuid" }, "artifact": { "type": "string", "maxLength": 174764 }, "confirm": { "const": true } }, "required": [ "action", "request_id", "artifact", "confirm" ] } ] }, "example": { "action": "prepare", "request_id": "00000000-0000-0000-0000-000000000001" } } } } } }, "/internal/v1/settings/image-verification": { "get": { "operationId": "management_get_internal_v1_settings_image_verification", "summary": "Read verification settings", "description": "Read verification settings. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read verification settings response", "content": { "application/json": { "schema": { "title": "ManagementSettingsImageVerificationResponse", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "daily", "weekly" ] }, "hour_utc": { "type": "integer", "minimum": 0, "maximum": 23 }, "last_run": { "title": "ManagementSettingsImageVerificationResponseLast_Run", "type": "object", "properties": { "at": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "outcome": { "type": [ "string", "null" ] }, "matched": { "type": [ "integer", "null" ] }, "mismatched": { "type": [ "integer", "null" ] }, "not_in_feed": { "type": [ "integer", "null" ] } }, "required": [ "at", "source", "outcome", "matched", "mismatched", "not_in_feed" ], "additionalProperties": true } }, "required": [ "mode", "hour_utc", "last_run" ], "additionalProperties": true }, "example": { "mode": "daily", "hour_utc": 3, "last_run": { "at": null, "source": null, "outcome": null, "matched": null, "mismatched": null, "not_in_feed": null } } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "management_post_internal_v1_settings_image_verification", "summary": "Update verification settings", "description": "Update verification settings. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Update verification settings response", "content": { "application/json": { "schema": { "title": "ManagementSettingsImageVerificationResponse", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "daily", "weekly" ] }, "hour_utc": { "type": "integer", "minimum": 0, "maximum": 23 }, "last_run": { "title": "ManagementSettingsImageVerificationResponseLast_Run", "type": "object", "properties": { "at": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "outcome": { "type": [ "string", "null" ] }, "matched": { "type": [ "integer", "null" ] }, "mismatched": { "type": [ "integer", "null" ] }, "not_in_feed": { "type": [ "integer", "null" ] } }, "required": [ "at", "source", "outcome", "matched", "mismatched", "not_in_feed" ], "additionalProperties": true } }, "required": [ "mode", "hour_utc", "last_run" ], "additionalProperties": true }, "example": { "mode": "daily", "hour_utc": 3, "last_run": { "at": null, "source": null, "outcome": null, "matched": null, "mismatched": null, "not_in_feed": null } } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementSettingsImageVerificationRequest", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "daily", "weekly" ] }, "hour_utc": { "type": "integer", "minimum": 0, "maximum": 23 } }, "required": [ "mode" ], "additionalProperties": true }, "example": { "mode": "daily", "hour_utc": 3 } } } } } }, "/internal/v1/settings/audit-export": { "post": { "operationId": "management_post_internal_v1_settings_audit_export", "summary": "Update audit export settings", "description": "Update audit export settings. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Update audit export settings response", "content": { "application/json": { "schema": { "title": "ManagementSettingsAuditExportResponse", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementSettingsAuditExportRequest", "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "integer" }, "user": { "type": "string" }, "path": { "type": "string" }, "age_recipient": { "type": "string" }, "auto": { "type": "boolean" }, "password": { "type": "string", "format": "password", "writeOnly": true, "description": "Required for first configuration or recovery after an interrupted save/clear leaves the destination unconfigured. An absent or empty password keeps the stored secret only when the existing configuration is valid. Must not contain U+0000 (NUL)." } }, "required": [ "host", "user", "path", "age_recipient" ], "additionalProperties": true }, "example": { "host": "audit.example", "port": 22, "user": "iris", "path": "/archive/iris", "age_recipient": "age1example", "auto": true, "password": "transport-password" } } } } }, "delete": { "operationId": "management_delete_internal_v1_settings_audit_export", "summary": "Delete audit export settings", "description": "Delete audit export settings. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Delete audit export settings response", "content": { "application/json": { "schema": { "title": "ManagementSettingsAuditExportResponse", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": true }, "example": { "deleted": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/settings/audit-export/run": { "post": { "operationId": "management_post_internal_v1_settings_audit_export_run", "summary": "Start audit export", "description": "Start audit export. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Start audit export response", "content": { "application/json": { "schema": { "title": "ManagementSettingsAuditExportRunResponse", "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ], "additionalProperties": true }, "example": { "job_id": "job-01" } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementSettingsAuditExportRunRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/internal/v1/settings/audit-export/run/{job_id}": { "get": { "operationId": "management_get_internal_v1_settings_audit_export_run_job_id", "summary": "Read audit export job", "description": "Read audit export job. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" } ], "responses": { "200": { "description": "Read audit export job response", "content": { "application/json": { "schema": { "title": "ManagementSettingsAuditExportRunJobIdResponse", "type": "object", "properties": { "state": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "state", "detail" ], "additionalProperties": true }, "example": { "state": "running", "detail": "" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API" } }, "/internal/v1/settings/ca-trust": { "post": { "operationId": "management_post_internal_v1_settings_ca_trust", "summary": "Update CA trust settings", "description": "Update CA trust settings. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Update CA trust settings response", "content": { "application/json": { "schema": { "title": "ManagementSettingsCaTrustResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "ca_trust": { "title": "ManagementSettingsCaTrustResponseCa_Trust", "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "auto": { "type": "boolean" } }, "required": [ "url", "auto" ], "additionalProperties": true } }, "required": [ "ok", "ca_trust" ], "additionalProperties": true }, "example": { "ok": true, "ca_trust": { "url": "https://example.invalid/ca.pem", "auto": true } } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementSettingsCaTrustRequest", "type": "object", "properties": { "url": { "type": [ "string", "null" ], "format": "uri" }, "auto": { "type": "boolean" } }, "required": [], "additionalProperties": true }, "example": { "url": null, "auto": true } } } } } }, "/internal/v1/settings/ca-trust/refresh": { "post": { "operationId": "management_post_internal_v1_settings_ca_trust_refresh", "summary": "Start CA trust refresh", "description": "Start CA trust refresh. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8-128 safe characters; replays the same successful response for 24 hours within one management process", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "onboard-edge-01-0001" } ], "responses": { "200": { "description": "Start CA trust refresh response", "content": { "application/json": { "schema": { "title": "ManagementSettingsCaTrustRefreshResponse", "type": "object", "properties": { "job": { "type": "string" } }, "required": [ "job" ], "additionalProperties": true }, "example": { "job": "job-01" } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-idempotency": "process-local-24h-success-replay", "x-iris-v1-resource-path-exception": "settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API", "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementSettingsCaTrustRefreshRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/internal/v1/settings/ca-trust/refresh/{job_id}": { "get": { "operationId": "management_get_internal_v1_settings_ca_trust_refresh_job_id", "summary": "Read CA trust refresh job", "description": "Read CA trust refresh job. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" } ], "responses": { "200": { "description": "Read CA trust refresh job response", "content": { "application/json": { "schema": { "title": "ManagementSettingsCaTrustRefreshJobIdResponse", "type": "object", "properties": { "state": { "type": "string" }, "detail": { "type": "string" }, "certs": { "type": [ "integer", "null" ] } }, "required": [ "state", "detail", "certs" ], "additionalProperties": true }, "example": { "state": "running", "detail": "", "certs": null } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-iris-v1-resource-path-exception": "settings command: retained for the shipped console and the one-to-one BFF/management dispatch boundary; a rename would be breaking and is reserved for a future major API" } }, "/internal/v1/settings/telemetry-destination": { "post": { "operationId": "management_post_internal_v1_settings_telemetry_destination", "summary": "Update telemetry destination", "description": "Update telemetry destination. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Update telemetry destination response", "content": { "application/json": { "schema": { "title": "ManagementSettingsTelemetryDestinationResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "endpoint": { "type": [ "string", "null" ], "format": "uri" }, "enabled": { "type": [ "boolean", "null" ] } }, "required": [ "ok", "endpoint", "enabled" ], "additionalProperties": true }, "example": { "ok": true, "endpoint": null, "enabled": null } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "ManagementSettingsTelemetryDestinationRequest", "type": "object", "properties": { "endpoint": { "type": [ "string", "null" ], "format": "uri" }, "enabled": { "type": [ "boolean", "null" ] } }, "required": [], "additionalProperties": true }, "example": { "endpoint": null, "enabled": null } } } } }, "delete": { "operationId": "management_delete_internal_v1_settings_telemetry_destination", "summary": "Delete telemetry destination", "description": "Delete telemetry destination. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Delete telemetry destination response", "content": { "application/json": { "schema": { "title": "ManagementSettingsTelemetryDestinationResponse", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": true }, "example": { "deleted": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/settings/gui-cert": { "post": { "operationId": "management_post_internal_v1_settings_gui_cert", "summary": "Install console certificate", "description": "Install console certificate. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Install console certificate response", "content": { "application/json": { "schema": { "title": "ManagementSettingsGuiCertResponse", "type": "object", "properties": { "gui_cert": { "title": "ManagementSettingsGuiCertResponseGui_Cert", "type": "object", "properties": { "source": { "type": "string" }, "subject": { "type": "string" }, "issuer": { "type": "string" }, "not_after": { "type": "string" }, "fingerprint_sha256": { "type": "string" } }, "required": [ "source", "subject", "issuer", "not_after", "fingerprint_sha256" ], "additionalProperties": true }, "applied": { "type": "boolean" }, "note": { "type": [ "string", "null" ] } }, "required": [ "gui_cert", "applied", "note" ], "additionalProperties": true }, "example": { "gui_cert": { "source": "custom", "subject": "CN=iris.example", "issuer": "CN=IRIS CA", "not_after": "Sep 4 00:00:00 2027 GMT", "fingerprint_sha256": "0000000000000000000000000000000000000000000000000000000000000000" }, "applied": true, "note": null } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementSettingsGuiCertRequest", "type": "object", "properties": { "cert_pem": { "type": "string" }, "key_pem": { "type": "string" }, "key_passphrase": { "type": "string", "format": "password", "writeOnly": true } }, "required": [ "cert_pem", "key_pem" ], "additionalProperties": true }, "example": { "cert_pem": "-----BEGIN CERTIFICATE-----\n...", "key_pem": "-----BEGIN PRIVATE KEY-----\n...", "key_passphrase": "optional-passphrase" } } } } }, "delete": { "operationId": "management_delete_internal_v1_settings_gui_cert", "summary": "Remove console certificate", "description": "Remove console certificate. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Remove console certificate response", "content": { "application/json": { "schema": { "title": "ManagementSettingsGuiCertResponse", "type": "object", "properties": { "deleted": { "type": "boolean" }, "gui_cert": { "title": "ManagementSettingsGuiCertResponseGui_Cert", "type": "object", "properties": { "source": { "type": "string" }, "subject": { "type": "string" }, "issuer": { "type": "string" }, "not_after": { "type": "string" }, "fingerprint_sha256": { "type": "string" } }, "required": [ "source", "subject", "issuer", "not_after", "fingerprint_sha256" ], "additionalProperties": true } }, "required": [ "deleted", "gui_cert" ], "additionalProperties": true }, "example": { "deleted": true, "gui_cert": { "source": "built-in", "subject": "CN=iris.example", "issuer": "CN=IRIS CA", "not_after": "Sep 4 00:00:00 2027 GMT", "fingerprint_sha256": "0000000000000000000000000000000000000000000000000000000000000000" } } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/settings/trust": { "post": { "operationId": "management_post_internal_v1_settings_trust", "summary": "Install a trust anchor", "description": "Install a trust anchor. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Install a trust anchor response", "content": { "application/json": { "schema": { "title": "ManagementSettingsTrustResponse", "type": "object", "properties": { "entry": { "title": "ManagementSettingsTrustResponseEntry", "type": "object", "properties": { "name": { "type": "string" }, "subject": { "type": "string" }, "fingerprint_sha256": { "type": "string" } }, "required": [ "name", "subject", "fingerprint_sha256" ], "additionalProperties": true } }, "required": [ "entry" ], "additionalProperties": true }, "example": { "entry": { "name": "ca-example.pem", "subject": "CN=Example CA", "fingerprint_sha256": "0000000000000000000000000000000000000000000000000000000000000000" } } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementSettingsTrustRequest", "type": "object", "properties": { "pem": { "type": "string" } }, "required": [ "pem" ], "additionalProperties": true }, "example": { "pem": "-----BEGIN CERTIFICATE-----\n..." } } } } } }, "/internal/v1/settings/trust/{name}": { "delete": { "operationId": "management_delete_internal_v1_settings_trust_name", "summary": "Delete a trust anchor", "description": "Delete a trust anchor. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "200": { "description": "Delete a trust anchor response", "content": { "application/json": { "schema": { "title": "ManagementSettingsTrustNameResponse", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": true }, "example": { "deleted": true } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/help": { "get": { "operationId": "management_get_internal_v1_help", "summary": "Read help metadata", "description": "Read help metadata. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Read help metadata response", "content": { "application/json": { "schema": { "title": "ManagementHelpResponse", "type": "object", "properties": { "version": { "type": "string" }, "deployment_id": { "type": "string" }, "docs_url": { "type": "string", "format": "uri" }, "guides": { "title": "ManagementHelpResponseGuides", "type": "object", "properties": { "device": { "type": "string" }, "server": { "type": "string" } }, "required": [ "device", "server" ], "additionalProperties": true } }, "required": [ "version", "deployment_id", "docs_url", "guides" ], "additionalProperties": true }, "example": { "version": "2026.09.04", "deployment_id": "deployment-01", "docs_url": "https://cisco-open.github.io/intelligent-release-image-staging/docs/", "guides": { "device": "/help-device.html", "server": "/help-server.html" } } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/swarmmap": { "get": { "operationId": "management_get_internal_v1_swarmmap", "summary": "Open swarm map", "description": "Open swarm map. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Authenticated HTML application", "content": { "text/html": { "schema": { "type": "string" }, "example": "..." } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Service unavailable", "x-iris-problem-codes": [ "service-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/console-certificate": { "get": { "operationId": "management_get_internal_v1_console_certificate", "summary": "Read active console TLS identity", "description": "Read active console TLS identity. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [] } ], "parameters": [], "responses": { "200": { "description": "Active custom console identity; 204 selects the separately mounted default", "headers": { "X-IRIS-Certificate-Source": { "schema": { "type": "string", "enum": [ "custom", "built-in" ] } } }, "content": { "application/x-pem-file": { "schema": { "type": "string" }, "example": "" } } }, "204": { "description": "Use independently mounted default; no private key crosses tiers", "headers": { "X-IRIS-Certificate-Source": { "schema": { "type": "string", "const": "default" } } } }, "401": { "description": "Management authentication required", "x-iris-problem-codes": [ "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "503": { "description": "Console certificate unavailable", "x-iris-problem-codes": [ "console-certificate-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-certificate-unavailable", "title": "Console certificate unavailable", "status": 503, "code": "console-certificate-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/authorizations": { "post": { "operationId": "management_post_internal_v1_authorizations", "summary": "Authorize a browser mutation", "description": "Authorize a browser mutation. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [] } ], "parameters": [], "responses": { "204": { "description": "Headers authorized; no response body" }, "400": { "description": "Invalid authorization request", "x-iris-problem-codes": [ "invalid-authorization-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-authorization-request", "title": "Invalid authorization request", "status": 400, "code": "invalid-authorization-request" } } } }, "401": { "description": "Management authentication required or Console session required", "x-iris-problem-codes": [ "management-authentication-required", "console-session-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } }, "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "CSRF validation failed or Forbidden", "x-iris-problem-codes": [ "csrf-validation-failed", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf-validation-failed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "CSRF validation failed", "status": 403, "code": "csrf-validation-failed" } }, "forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } } } }, "404": { "description": "Resource not found or Route not found", "x-iris-problem-codes": [ "resource-not-found", "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resource-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } }, "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "ManagementAuthorizationsRequest", "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" } }, "required": [ "method", "path" ], "additionalProperties": false }, "example": { "method": "POST", "path": "/internal/v1/devices" } } } } } }, "/v1/images": { "get": { "operationId": "catalog_get_v1_images", "summary": "List assigned images", "description": "List assigned images. The device bearer is resource-bound. Image collections, items and torrents expose only that device's current assignment. This bounded v1 collection has no pagination parameter; adding one without a stable compatibility shape is deferred to the next major version.", "tags": [ "catalog" ], "x-iris-service": "catalog", "x-iris-security": "deviceBearer", "servers": [ { "url": "https://iris.example:8443", "description": "Device catalog" } ], "security": [ { "deviceBearer": [] } ], "parameters": [], "responses": { "200": { "description": "List assigned images response", "content": { "application/json": { "schema": { "title": "CatalogV1ImagesResponse", "type": "object", "properties": { "images": { "type": "array", "items": { "title": "CatalogV1ImagesResponseImagesItem", "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer" }, "sha256": { "type": "string" } }, "required": [ "id", "filename", "size", "sha256" ], "additionalProperties": true } } }, "required": [ "images" ], "additionalProperties": true }, "example": { "images": [ { "id": "image-01", "filename": "image.bin", "size": 1048576, "sha256": "0000000000000000000000000000000000000000000000000000000000000000" } ] } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Catalog authentication required", "x-iris-problem-codes": [ "catalog-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#catalog-authentication-required", "title": "Catalog authentication required", "status": 401, "code": "catalog-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found", "x-iris-problem-codes": [ "resource-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Credential store unavailable", "x-iris-problem-codes": [ "credential-store-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/v1/images/{image_id}": { "get": { "operationId": "catalog_get_v1_images_image_id", "summary": "Read assigned image", "description": "Read assigned image. The device bearer is resource-bound. Image collections, items and torrents expose only that device's current assignment.", "tags": [ "catalog" ], "x-iris-service": "catalog", "x-iris-security": "deviceBearer", "servers": [ { "url": "https://iris.example:8443", "description": "Device catalog" } ], "security": [ { "deviceBearer": [] } ], "parameters": [ { "name": "image_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" } ], "responses": { "200": { "description": "Read assigned image response", "content": { "application/json": { "schema": { "title": "CatalogV1ImagesImageIdResponse", "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer" }, "sha256": { "type": "string" } }, "required": [ "id", "filename", "size", "sha256" ], "additionalProperties": true }, "example": { "id": "image-01", "filename": "image.bin", "size": 1048576, "sha256": "0000000000000000000000000000000000000000000000000000000000000000" } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Catalog authentication required", "x-iris-problem-codes": [ "catalog-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#catalog-authentication-required", "title": "Catalog authentication required", "status": 401, "code": "catalog-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found", "x-iris-problem-codes": [ "resource-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Credential store unavailable", "x-iris-problem-codes": [ "credential-store-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/v1/torrents/{image_id}": { "get": { "operationId": "catalog_get_v1_torrents_image_id", "summary": "Download personalized torrent", "description": "Download personalized torrent. The device bearer is resource-bound. Image collections, items and torrents expose only that device's current assignment.", "tags": [ "catalog" ], "x-iris-service": "catalog", "x-iris-security": "deviceBearer", "servers": [ { "url": "https://iris.example:8443", "description": "Device catalog" } ], "security": [ { "deviceBearer": [] } ], "parameters": [ { "name": "image_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "example-id" }, { "name": "X-IRIS-Tracker-Auth", "in": "header", "required": false, "description": "Set exactly to bearer by unified IOx/XR agents for a token-free announce URL. Omit for Guest Shell query-auth torrents.", "schema": { "type": "string", "const": "bearer" }, "example": "bearer" } ], "responses": { "200": { "description": "Device-personalized BitTorrent metainfo", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization, X-IRIS-Tracker-Auth" } } }, "content": { "application/x-bittorrent": { "schema": {}, "example": "" } } }, "400": { "description": "Invalid tracker authentication selector or Invalid request", "x-iris-problem-codes": [ "invalid-tracker-auth-selector", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-tracker-auth-selector": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-tracker-auth-selector", "title": "Invalid tracker authentication selector", "status": 400, "code": "invalid-tracker-auth-selector" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Catalog authentication required", "x-iris-problem-codes": [ "catalog-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#catalog-authentication-required", "title": "Catalog authentication required", "status": 401, "code": "catalog-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found", "x-iris-problem-codes": [ "resource-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Credential store unavailable", "x-iris-problem-codes": [ "credential-store-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/v1/devices/{device_id}/policy": { "get": { "operationId": "catalog_get_v1_devices_device_id_policy", "summary": "Read device policy", "description": "Read device policy. The device bearer is resource-bound. Image collections, items and torrents expose only that device's current assignment.", "tags": [ "catalog" ], "x-iris-service": "catalog", "x-iris-security": "deviceBearer", "servers": [ { "url": "https://iris.example:8443", "description": "Device catalog" } ], "security": [ { "deviceBearer": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" } ], "responses": { "200": { "description": "Read device policy response", "content": { "application/json": { "schema": { "title": "CatalogV1DevicesDeviceIdPolicyResponse", "type": "object", "properties": { "approved_image_id": { "type": [ "string", "null" ] }, "approved_image_ids": { "type": "array", "items": { "type": "string" } }, "plans": { "type": "object", "additionalProperties": { "type": "object", "properties": { "plan_id": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "transfer_id": { "type": "string", "pattern": "^[0-9a-f]{32}$" } }, "required": [ "plan_id", "transfer_id" ], "additionalProperties": false } }, "instr_rev": { "type": "object", "required": [ "epoch", "instr_serial" ], "additionalProperties": false, "properties": { "epoch": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "instr_serial": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } }, "description": "Pointer from the complete stored stamp only; absent before stamping. Role/cadence failure does not remove a valid pointer." }, "keylist_seq": { "type": "integer", "minimum": 1, "maximum": 9223372036854775807, "description": "Monotonic sequence parsed from the installed signed artifact; omitted when uninitialized or unavailable without failing policy/heartbeat." } }, "required": [ "approved_image_id", "approved_image_ids", "plans" ], "additionalProperties": true }, "examples": { "instructionsAvailable": { "value": { "approved_image_id": null, "approved_image_ids": [ "image-01" ], "plans": { "image-01": { "plan_id": "0123456789abcdef0123456789abcdef", "transfer_id": "fedcba9876543210fedcba9876543210" } }, "instr_rev": { "epoch": 1788782400, "instr_serial": 7 }, "keylist_seq": 8 } }, "legacyOrUnavailable": { "value": { "approved_image_id": null, "approved_image_ids": [ "image-01" ], "plans": { "image-01": { "plan_id": "0123456789abcdef0123456789abcdef", "transfer_id": "fedcba9876543210fedcba9876543210" } } } } } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Catalog authentication required", "x-iris-problem-codes": [ "catalog-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#catalog-authentication-required", "title": "Catalog authentication required", "status": 401, "code": "catalog-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found", "x-iris-problem-codes": [ "resource-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Credential store unavailable", "x-iris-problem-codes": [ "credential-store-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/v1/devices/{device_id}/instructions": { "get": { "operationId": "catalog_get_v1_devices_device_id_instructions", "summary": "Read sealed device instructions", "description": "Read sealed device instructions. Only the current same-device catalog Bearer is accepted. Previous catalog tokens are limited to token-refresh. Missing/malformed Bearer returns 401 before any store access; usable Bearer meets strict credential-store validation before dispatch (503 on unavailable state). A valid credential naming another device returns 403 without revealing target existence. Both instruction routes share one process-local per-device token bucket: burst 2, refill one token per 10 seconds, 20,000 device bound, and 20-second idle pruning. Body, 304 and later resource-error requests all consume a token; authentication/authorization failures do not. Retry-After on 429 is max(1, ceil((1 - tokens) * 10)). Restart resets the limiter; multiple processes or replicas multiply the allowance. The supported deployment uses one catalog process/replica. No instruction keys, role artifacts or signatures have separate delivery aliases. Device verifier roots use only the exact artifact and bundle trust files; IRIS stages images only. Reconstructs at most 256 KiB from one stored stamp and its validated immutable role artifact. The exact stamped non-revoked current key remains eligible regardless of rotation-trigger expiry; a non-revoked previous key is eligible only before its overlap deadline. Every response, including cache hits and 304, rechecks complete state and key eligibility. Missing stamp/named file returns counted 404; an unavailable stamped key returns stale_pointer 409. server_time equals stored issued_at; current HTTP Date does not change envelope bytes. The process-memory ciphertext cache is bounded at 256 entries and 16 MiB; per-device ciphertext is never persisted.", "tags": [ "catalog" ], "x-iris-service": "catalog", "x-iris-security": "deviceBearer", "servers": [ { "url": "https://iris.example:8443", "description": "Device catalog" } ], "security": [ { "deviceBearer": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9110 weak comparison for GET: accepts a weak or strong tag, a comma-separated list, or wildcard *. Multiple field lines form one list. Invalid syntax and nonmatches return the ordinary response. Authentication, limiter admission and current state/key validation precede matching.", "example": "W/\"sha256-0000000000000000000000000000000000000000000000000000000000000000\"" } ], "responses": { "200": { "description": "Exact IRIS-INSTR/2 framed bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Date": { "schema": { "type": "string" }, "description": "Current RFC 9110 HTTP-date; independent of immutable envelope server_time and ETag", "example": "Mon, 07 Sep 2026 12:00:00 GMT" }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "ETag": { "schema": { "type": "string", "pattern": "^\"sha256-[0-9a-f]{64}\"$" }, "description": "Strong SHA-256 digest of the exact selected response bytes", "example": "\"sha256-0000000000000000000000000000000000000000000000000000000000000000\"" } }, "content": { "application/octet-stream": { "schema": {}, "example": "" } } }, "304": { "description": "Selected representation matches If-None-Match after current authorization, limiter and state checks; no body, Content-Type or Content-Length", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Date": { "schema": { "type": "string" }, "description": "Current RFC 9110 HTTP-date; independent of immutable envelope server_time and ETag", "example": "Mon, 07 Sep 2026 12:00:00 GMT" }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "ETag": { "schema": { "type": "string", "pattern": "^\"sha256-[0-9a-f]{64}\"$" }, "description": "Strong SHA-256 digest of the exact selected response bytes", "example": "\"sha256-0000000000000000000000000000000000000000000000000000000000000000\"" } } }, "401": { "description": "Catalog authentication required", "x-iris-problem-codes": [ "catalog-authentication-required" ], "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "title", "status", "code" ], "additionalProperties": false, "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#catalog-authentication-required" }, "title": { "const": "Catalog authentication required" }, "status": { "const": 401 }, "code": { "const": "catalog-authentication-required" } } }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#catalog-authentication-required", "title": "Catalog authentication required", "status": 401, "code": "catalog-authentication-required" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Date": { "schema": { "type": "string" }, "description": "Current RFC 9110 HTTP-date; independent of immutable envelope server_time and ETag", "example": "Mon, 07 Sep 2026 12:00:00 GMT" }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } } }, "403": { "description": "Instruction access forbidden", "x-iris-problem-codes": [ "instruction-device-forbidden" ], "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "title", "status", "code" ], "additionalProperties": false, "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-device-forbidden" }, "title": { "const": "Instruction access forbidden" }, "status": { "const": 403 }, "code": { "const": "instruction-device-forbidden" } } }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-device-forbidden", "title": "Instruction access forbidden", "status": 403, "code": "instruction-device-forbidden" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Date": { "schema": { "type": "string" }, "description": "Current RFC 9110 HTTP-date; independent of immutable envelope server_time and ETag", "example": "Mon, 07 Sep 2026 12:00:00 GMT" }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } } } }, "404": { "description": "Instruction stamp missing", "x-iris-problem-codes": [ "instruction-stamp-missing" ], "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "title", "status", "code" ], "additionalProperties": false, "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-stamp-missing" }, "title": { "const": "Instruction stamp missing" }, "status": { "const": 404 }, "code": { "const": "instruction-stamp-missing" } } }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-stamp-missing", "title": "Instruction stamp missing", "status": 404, "code": "instruction-stamp-missing" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Date": { "schema": { "type": "string" }, "description": "Current RFC 9110 HTTP-date; independent of immutable envelope server_time and ETag", "example": "Mon, 07 Sep 2026 12:00:00 GMT" }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } } } }, "409": { "description": "Stale instruction pointer", "x-iris-problem-codes": [ "stale_pointer" ], "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "title", "status", "code" ], "additionalProperties": false, "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#stale_pointer" }, "title": { "const": "Stale instruction pointer" }, "status": { "const": 409 }, "code": { "const": "stale_pointer" } } }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#stale_pointer", "title": "Stale instruction pointer", "status": 409, "code": "stale_pointer" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Date": { "schema": { "type": "string" }, "description": "Current RFC 9110 HTTP-date; independent of immutable envelope server_time and ETag", "example": "Mon, 07 Sep 2026 12:00:00 GMT" }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1, "const": 10 }, "example": 10, "description": "Retry after ten seconds" } } }, "429": { "description": "Instruction request rate limit exceeded", "x-iris-problem-codes": [ "instruction-rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "title", "status", "code" ], "additionalProperties": false, "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-rate-limit-exceeded" }, "title": { "const": "Instruction request rate limit exceeded" }, "status": { "const": 429 }, "code": { "const": "instruction-rate-limit-exceeded" } } }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-rate-limit-exceeded", "title": "Instruction request rate limit exceeded", "status": 429, "code": "instruction-rate-limit-exceeded" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Date": { "schema": { "type": "string" }, "description": "Current RFC 9110 HTTP-date; independent of immutable envelope server_time and ETag", "example": "Mon, 07 Sep 2026 12:00:00 GMT" }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "example": 1, "description": "Computed seconds until one limiter token is available" } } }, "503": { "description": "Credential store unavailable or Instruction state unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "instruction-state-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "required": [ "type", "title", "status", "code" ], "additionalProperties": false, "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "const": "Credential store unavailable" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } } }, { "type": "object", "required": [ "type", "title", "status", "code" ], "additionalProperties": false, "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-state-unavailable" }, "title": { "const": "Instruction state unavailable" }, "status": { "const": 503 }, "code": { "const": "instruction-state-unavailable" } } } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "instruction-state-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-state-unavailable", "title": "Instruction state unavailable", "status": 503, "code": "instruction-state-unavailable" } } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Date": { "schema": { "type": "string" }, "description": "Current RFC 9110 HTTP-date; independent of immutable envelope server_time and ETag", "example": "Mon, 07 Sep 2026 12:00:00 GMT" }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1, "const": 10 }, "example": 10, "description": "Retry after ten seconds" } } } } } }, "/v1/devices/{device_id}/instruction-keylist": { "get": { "operationId": "catalog_get_v1_devices_device_id_instruction_keylist", "summary": "Read installed instruction keylist", "description": "Read installed instruction keylist. Only the current same-device catalog Bearer is accepted. Previous catalog tokens are limited to token-refresh. Missing/malformed Bearer returns 401 before any store access; usable Bearer meets strict credential-store validation before dispatch (503 on unavailable state). A valid credential naming another device returns 403 without revealing target existence. Both instruction routes share one process-local per-device token bucket: burst 2, refill one token per 10 seconds, 20,000 device bound, and 20-second idle pruning. Body, 304 and later resource-error requests all consume a token; authentication/authorization failures do not. Retry-After on 429 is max(1, ceil((1 - tokens) * 10)). Restart resets the limiter; multiple processes or replicas multiply the allowance. The supported deployment uses one catalog process/replica. No instruction keys, role artifacts or signatures have separate delivery aliases. Device verifier roots use only the exact artifact and bundle trust files; IRIS stages images only. Serves at most 128 KiB of the exact installed root-signed keylist, including a KRL of at most 80 KiB. Both artifact and metadata absent means uninitialized 404; established artifact loss or contradictory/corrupt state means 503. An artifact ahead of its metadata remains authoritative and serveable. No signature verification, root discovery or repair occurs on GET.", "tags": [ "catalog" ], "x-iris-service": "catalog", "x-iris-security": "deviceBearer", "servers": [ { "url": "https://iris.example:8443", "description": "Device catalog" } ], "security": [ { "deviceBearer": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9110 weak comparison for GET: accepts a weak or strong tag, a comma-separated list, or wildcard *. Multiple field lines form one list. Invalid syntax and nonmatches return the ordinary response. Authentication, limiter admission and current state/key validation precede matching.", "example": "W/\"sha256-0000000000000000000000000000000000000000000000000000000000000000\"" } ], "responses": { "200": { "description": "Exact IRIS-KEYLIST/1 framed bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Date": { "schema": { "type": "string" }, "description": "Current RFC 9110 HTTP-date; independent of immutable envelope server_time and ETag", "example": "Mon, 07 Sep 2026 12:00:00 GMT" }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "ETag": { "schema": { "type": "string", "pattern": "^\"sha256-[0-9a-f]{64}\"$" }, "description": "Strong SHA-256 digest of the exact selected response bytes", "example": "\"sha256-0000000000000000000000000000000000000000000000000000000000000000\"" } }, "content": { "application/octet-stream": { "schema": {}, "example": "" } } }, "304": { "description": "Selected representation matches If-None-Match after current authorization, limiter and state checks; no body, Content-Type or Content-Length", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Date": { "schema": { "type": "string" }, "description": "Current RFC 9110 HTTP-date; independent of immutable envelope server_time and ETag", "example": "Mon, 07 Sep 2026 12:00:00 GMT" }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "ETag": { "schema": { "type": "string", "pattern": "^\"sha256-[0-9a-f]{64}\"$" }, "description": "Strong SHA-256 digest of the exact selected response bytes", "example": "\"sha256-0000000000000000000000000000000000000000000000000000000000000000\"" } } }, "401": { "description": "Catalog authentication required", "x-iris-problem-codes": [ "catalog-authentication-required" ], "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "title", "status", "code" ], "additionalProperties": false, "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#catalog-authentication-required" }, "title": { "const": "Catalog authentication required" }, "status": { "const": 401 }, "code": { "const": "catalog-authentication-required" } } }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#catalog-authentication-required", "title": "Catalog authentication required", "status": 401, "code": "catalog-authentication-required" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Date": { "schema": { "type": "string" }, "description": "Current RFC 9110 HTTP-date; independent of immutable envelope server_time and ETag", "example": "Mon, 07 Sep 2026 12:00:00 GMT" }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } } }, "403": { "description": "Instruction access forbidden", "x-iris-problem-codes": [ "instruction-device-forbidden" ], "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "title", "status", "code" ], "additionalProperties": false, "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-device-forbidden" }, "title": { "const": "Instruction access forbidden" }, "status": { "const": 403 }, "code": { "const": "instruction-device-forbidden" } } }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-device-forbidden", "title": "Instruction access forbidden", "status": 403, "code": "instruction-device-forbidden" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Date": { "schema": { "type": "string" }, "description": "Current RFC 9110 HTTP-date; independent of immutable envelope server_time and ETag", "example": "Mon, 07 Sep 2026 12:00:00 GMT" }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } } } }, "404": { "description": "Instruction keylist missing", "x-iris-problem-codes": [ "instruction-keylist-missing" ], "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "title", "status", "code" ], "additionalProperties": false, "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-keylist-missing" }, "title": { "const": "Instruction keylist missing" }, "status": { "const": 404 }, "code": { "const": "instruction-keylist-missing" } } }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-keylist-missing", "title": "Instruction keylist missing", "status": 404, "code": "instruction-keylist-missing" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Date": { "schema": { "type": "string" }, "description": "Current RFC 9110 HTTP-date; independent of immutable envelope server_time and ETag", "example": "Mon, 07 Sep 2026 12:00:00 GMT" }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } } } }, "429": { "description": "Instruction request rate limit exceeded", "x-iris-problem-codes": [ "instruction-rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "title", "status", "code" ], "additionalProperties": false, "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-rate-limit-exceeded" }, "title": { "const": "Instruction request rate limit exceeded" }, "status": { "const": 429 }, "code": { "const": "instruction-rate-limit-exceeded" } } }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-rate-limit-exceeded", "title": "Instruction request rate limit exceeded", "status": 429, "code": "instruction-rate-limit-exceeded" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Date": { "schema": { "type": "string" }, "description": "Current RFC 9110 HTTP-date; independent of immutable envelope server_time and ETag", "example": "Mon, 07 Sep 2026 12:00:00 GMT" }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "example": 1, "description": "Computed seconds until one limiter token is available" } } }, "503": { "description": "Credential store unavailable or Instruction keylist unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "instruction-keylist-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "required": [ "type", "title", "status", "code" ], "additionalProperties": false, "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "const": "Credential store unavailable" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } } }, { "type": "object", "required": [ "type", "title", "status", "code" ], "additionalProperties": false, "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-keylist-unavailable" }, "title": { "const": "Instruction keylist unavailable" }, "status": { "const": 503 }, "code": { "const": "instruction-keylist-unavailable" } } } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "instruction-keylist-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#instruction-keylist-unavailable", "title": "Instruction keylist unavailable", "status": 503, "code": "instruction-keylist-unavailable" } } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Date": { "schema": { "type": "string" }, "description": "Current RFC 9110 HTTP-date; independent of immutable envelope server_time and ETag", "example": "Mon, 07 Sep 2026 12:00:00 GMT" }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1, "const": 10 }, "example": 10, "description": "Retry after ten seconds" } } } } } }, "/v1/devices/{device_id}/heartbeat": { "post": { "operationId": "catalog_post_v1_devices_device_id_heartbeat", "summary": "Record heartbeat", "description": "Record heartbeat. The device bearer is resource-bound. Image collections, items and torrents expose only that device's current assignment.", "tags": [ "catalog" ], "x-iris-service": "catalog", "x-iris-security": "deviceBearer", "servers": [ { "url": "https://iris.example:8443", "description": "Device catalog" } ], "security": [ { "deviceBearer": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" } ], "responses": { "200": { "description": "Record heartbeat response", "content": { "application/json": { "schema": { "title": "CatalogV1DevicesDeviceIdHeartbeatResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "stream_every": { "type": "integer", "minimum": 1, "maximum": 60, "description": "The one server-resolved telemetry cadence reused for observation validation, retention and response; global settings supply the fallback." }, "stream_pause": { "type": "boolean" }, "instr_rev": { "type": "object", "required": [ "epoch", "instr_serial" ], "additionalProperties": false, "properties": { "epoch": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "instr_serial": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } }, "description": "Pointer from the complete stored stamp only; absent before stamping. Role/cadence failure does not remove a valid pointer." }, "keylist_seq": { "type": "integer", "minimum": 1, "maximum": 9223372036854775807, "description": "Monotonic sequence parsed from the installed signed artifact; omitted when uninitialized or unavailable without failing policy/heartbeat." } }, "required": [ "ok", "stream_every", "stream_pause" ], "additionalProperties": true }, "examples": { "instructionsAvailable": { "value": { "ok": true, "stream_every": 4, "stream_pause": false, "instr_rev": { "epoch": 1788782400, "instr_serial": 7 }, "keylist_seq": 8 } }, "legacyOrUnavailable": { "value": { "ok": true, "stream_every": 4, "stream_pause": false } }, "fallbackCadence": { "value": { "ok": true, "stream_every": 4, "stream_pause": false } } } } } }, "400": { "description": "Invalid Content-Length or Invalid request body or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "invalid-request-body", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "invalid-request-body": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request-body", "title": "Invalid request body", "status": 400, "code": "invalid-request-body" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Catalog authentication required", "x-iris-problem-codes": [ "catalog-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#catalog-authentication-required", "title": "Catalog authentication required", "status": 401, "code": "catalog-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found", "x-iris-problem-codes": [ "resource-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Credential store unavailable", "x-iris-problem-codes": [ "credential-store-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "CatalogV1DevicesDeviceIdHeartbeatRequest", "type": "object", "properties": { "agent_version": { "type": "string" }, "telemetry_enabled": { "type": "boolean" }, "telemetry_stream_enabled": { "type": "boolean" }, "peer_tls": { "type": "object", "additionalProperties": false, "required": [ "configured_mode", "runtime_mode", "runtime_source" ], "properties": { "configured_mode": { "enum": [ "disabled", "required" ] }, "runtime_mode": { "enum": [ "disabled", "required", "unknown" ] }, "runtime_source": { "enum": [ "aria2_rpc", "unknown" ] }, "revocations": { "type": "object", "properties": { "supported": { "const": true }, "mode": { "enum": [ "required", "disabled" ] }, "state": { "enum": [ "valid", "unavailable", "expired" ] }, "authority": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "issued_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "expires_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "own_revoked": { "type": "boolean" }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "supported", "mode", "state", "authority", "revision", "issued_at", "expires_at", "own_revoked", "observed_at" ], "additionalProperties": false } }, "description": "Last reported torrent TLS daemon policy, not negotiated connection evidence. Missing means unknown." }, "peer_telemetry_v": { "type": "integer", "const": 1 }, "instr_protocol": { "type": [ "integer", "null" ], "enum": [ 1, null ], "description": "Protocol 1 identifies the current instruction projection; null records a present but unsupported or malformed marker. Absence identifies a pre-instructions agent." }, "applied": { "type": "object", "required": [ "bt_max_peers", "max_upload_limit", "max_download_limit", "overall_up", "overall_down", "request_peer_speed_limit", "max_concurrent" ], "additionalProperties": false, "properties": { "bt_max_peers": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "max_upload_limit": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "max_download_limit": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "overall_up": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "overall_down": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "request_peer_speed_limit": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "max_concurrent": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } }, "description": "Seven complete global/default aria2 observations, not per-GID claims. Omitted until successful assertion; retained for known LKG/fallback settings. Invalid objects are omitted as a whole." }, "instr_state": { "type": "string", "enum": [ "allowlist_expired", "applied", "audience_mismatch", "floor_reset", "instr_forbidden", "instr_pending", "instr_unavailable", "key_rejected", "lkg", "lkg_rejected", "lkg_unreadable", "none", "oversize", "reasserted", "rollback_rejected", "stale_expired", "tamper_rejected", "tracker-only", "verifier_missing" ] }, "instr_reason": { "type": "string", "enum": [ "bad_mac", "unknown_key" ] }, "instr_epoch": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "instr_serial": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "instr_policy_revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "pointer_skew": { "type": [ "boolean", "null" ] }, "verify_level": { "type": "string", "enum": [ "sig", "none" ] }, "blocklist_rules": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "blocklist_revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "qos_drift": { "type": "object", "required": [ "options" ], "additionalProperties": false, "properties": { "options": { "type": "array", "maxItems": 47, "items": { "type": "object", "required": [ "option", "expected", "observed" ], "additionalProperties": false, "properties": { "expected": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "observed": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "option": { "type": "string", "enum": [ "bt_max_peers", "max_upload_limit", "max_download_limit", "overall_up", "overall_down", "request_peer_speed_limit", "max_concurrent" ] } }, "description": "Non-Boolean integers; expected and observed must differ. Equality is rejected by the runtime sanitizer." } }, "blocklist_revision": { "type": "object", "required": [ "expected", "observed" ], "additionalProperties": false, "properties": { "expected": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "observed": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } }, "description": "Non-Boolean integers; expected and observed must differ. Equality is rejected by the runtime sanitizer." }, "blocklist_rules": { "type": "object", "required": [ "expected", "observed" ], "additionalProperties": false, "properties": { "expected": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "observed": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } }, "description": "Non-Boolean integers; expected and observed must differ. Equality is rejected by the runtime sanitizer." } }, "anyOf": [ { "properties": { "options": { "minItems": 1 } } }, { "required": [ "blocklist_revision" ] }, { "required": [ "blocklist_rules" ] } ], "description": "One bounded fact; preserves option order and duplicate observations. At most seven global/default plus four options for each of ten active GIDs. GIDs, scopes, indexes, addresses and arbitrary option names are never transmitted. Active GIDs contribute only bt_max_peers, max_upload_limit, max_download_limit or request_peer_speed_limit. Any invalid row or pair omits the whole fact." } }, "required": [], "additionalProperties": true, "dependentRequired": { "blocklist_rules": [ "blocklist_revision" ], "blocklist_revision": [ "blocklist_rules" ], "instr_epoch": [ "instr_serial", "instr_policy_revision" ], "instr_policy_revision": [ "instr_epoch", "instr_serial" ] }, "allOf": [ { "if": { "required": [ "instr_state" ], "properties": { "instr_state": { "const": "key_rejected" } } }, "then": { "required": [ "instr_reason" ] }, "else": { "not": { "required": [ "instr_reason" ] } } } ], "description": "Instruction fields are optional device assertions, not verified compliance. The server omits invalid state/reason and blocklist pairs as units; legacy agents omit all instruction fields. Integers exclude Boolean values and fractional or floating-point input. The accepted identity is either the complete epoch/serial/policy-revision triple or the legacy serial alone. Device role/platform, keys, signatures, peer lists and opaque aria2 option dictionaries are never accepted as attestation." }, "examples": { "applied": { "value": { "agent_version": "2026.09.04", "telemetry_enabled": true, "telemetry_stream_enabled": true, "instr_protocol": 1, "instr_state": "applied", "instr_epoch": 11, "instr_serial": 7, "instr_policy_revision": 3, "pointer_skew": false, "verify_level": "sig", "applied": { "bt_max_peers": 0, "max_upload_limit": 1, "max_download_limit": 2, "overall_up": 3, "overall_down": 4, "request_peer_speed_limit": 5, "max_concurrent": 6 }, "blocklist_rules": 12, "blocklist_revision": 3, "qos_drift": { "options": [ { "option": "max_upload_limit", "expected": 8192, "observed": 16384 } ] } } }, "keyRejected": { "value": { "agent_version": "2026.09.04", "telemetry_enabled": true, "telemetry_stream_enabled": true, "instr_protocol": 1, "instr_state": "key_rejected", "instr_reason": "unknown_key", "pointer_skew": false } }, "unknownCapability": { "value": { "agent_version": "2026.09.04", "telemetry_enabled": true, "telemetry_stream_enabled": true, "instr_protocol": null } }, "legacy": { "value": { "agent_version": "2026.09.04", "telemetry_enabled": true, "telemetry_stream_enabled": true } } } } } } } }, "/v1/devices/{device_id}/telemetry": { "post": { "operationId": "catalog_post_v1_devices_device_id_telemetry", "summary": "Record telemetry", "description": "Record telemetry. The device bearer is resource-bound. Image collections, items and torrents expose only that device's current assignment.", "tags": [ "catalog" ], "x-iris-service": "catalog", "x-iris-security": "deviceBearer", "servers": [ { "url": "https://iris.example:8443", "description": "Device catalog" } ], "security": [ { "deviceBearer": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" } ], "responses": { "200": { "description": "Record telemetry response", "content": { "application/json": { "schema": { "title": "CatalogV1DevicesDeviceIdTelemetryResponse", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "Invalid Content-Length or Invalid request body or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "invalid-request-body", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "invalid-request-body": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request-body", "title": "Invalid request body", "status": 400, "code": "invalid-request-body" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Catalog authentication required", "x-iris-problem-codes": [ "catalog-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#catalog-authentication-required", "title": "Catalog authentication required", "status": 401, "code": "catalog-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found", "x-iris-problem-codes": [ "resource-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Credential store unavailable", "x-iris-problem-codes": [ "credential-store-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "CatalogV1DevicesDeviceIdTelemetryRequest", "type": "object", "properties": { "schema": { "type": "string" }, "image_id": { "type": "string" }, "state": { "type": "string" }, "timestamp": { "type": "integer" } }, "required": [ "schema", "image_id" ], "additionalProperties": true }, "example": { "schema": "v2", "image_id": "image-01", "state": "complete", "timestamp": 1788470400 } } } } } }, "/v1/devices/{device_id}/live-telemetry": { "post": { "operationId": "catalog_post_v1_devices_device_id_live_telemetry", "summary": "Record accelerated live observation", "description": "Record accelerated live observation. The device bearer is resource-bound. Image collections, items and torrents expose only that device's current assignment.", "tags": [ "catalog" ], "x-iris-service": "catalog", "x-iris-security": "deviceBearer", "servers": [ { "url": "https://iris.example:8443", "description": "Device catalog" } ], "security": [ { "deviceBearer": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" } ], "responses": { "200": { "description": "Record accelerated live observation response", "content": { "application/json": { "schema": { "title": "CatalogV1DevicesDeviceIdLiveTelemetryResponse", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "example": { "ok": true } } } }, "400": { "description": "Invalid Content-Length or Invalid request body or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "invalid-request-body", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "invalid-request-body": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request-body", "title": "Invalid request body", "status": 400, "code": "invalid-request-body" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Catalog authentication required", "x-iris-problem-codes": [ "catalog-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#catalog-authentication-required", "title": "Catalog authentication required", "status": 401, "code": "catalog-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found", "x-iris-problem-codes": [ "resource-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Credential store unavailable", "x-iris-problem-codes": [ "credential-store-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "CatalogV1DevicesDeviceIdLiveTelemetryRequest", "type": "object", "properties": { "telemetry_observation": { "type": "object", "required": [ "v", "obs_state", "observed_at" ], "description": "At most 8192 serialized bytes. Requires current device credentials, an active ten-second signed policy, streaming enabled and a recent heartbeat. Unknown fields are discarded. Peer rows beyond 32 are truncated.", "properties": { "v": { "const": 2 }, "obs_state": { "enum": [ "observed", "not_due", "paused", "disabled", "not_active", "rpc_unavailable" ] }, "observed_at": { "type": "number", "minimum": 0 }, "image_id": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" }, "transfer_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "sample_seq": { "type": "integer", "minimum": 0 }, "sampling_class": { "enum": [ "good", "constrained" ] }, "aria": { "type": "object", "required": [ "completed_content_bytes", "total_content_bytes", "receive_bps", "send_bps", "connections" ], "properties": { "status": { "enum": [ "active", "waiting", "paused", "complete", "error", "removed" ] }, "completed_content_bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740992 }, "total_content_bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740992 }, "receive_bps": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "send_bps": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "connections": { "type": "integer", "minimum": 0, "maximum": 1024 } } }, "peer_connections": { "type": "array", "items": { "type": "object", "required": [ "ip" ], "properties": { "ip": { "type": "string", "format": "ipv4" }, "port": { "type": "integer", "minimum": 0, "maximum": 65535 }, "send_bps": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "receive_bps": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "peer_client_name": { "type": "string", "maxLength": 64 }, "progress": { "type": "number", "minimum": 0, "maximum": 100 } } } } }, "if": { "properties": { "obs_state": { "const": "observed" } } }, "then": { "required": [ "sample_seq", "sampling_class", "aria" ] }, "else": { "not": { "anyOf": [ { "required": [ "sampling_class" ] }, { "required": [ "aria" ] }, { "required": [ "peer_connections" ] } ] } } } }, "required": [ "telemetry_observation" ], "additionalProperties": false }, "example": { "telemetry_observation": { "v": 2, "obs_state": "rpc_unavailable", "observed_at": 1788470400, "image_id": "image-01", "transfer_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "sample_seq": 1 } } } } } } }, "/v1/devices/{device_id}/token-refresh": { "post": { "operationId": "catalog_post_v1_devices_device_id_token_refresh", "summary": "Rotate device token", "description": "Rotate device token. The device bearer is resource-bound. Image collections, items and torrents expose only that device's current assignment.", "tags": [ "catalog" ], "x-iris-service": "catalog", "x-iris-security": "deviceBearer", "servers": [ { "url": "https://iris.example:8443", "description": "Device catalog" } ], "security": [ { "deviceBearer": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" } ], "responses": { "200": { "description": "Rotate device token response", "content": { "application/json": { "schema": { "title": "CatalogV1DevicesDeviceIdTokenRefreshResponse", "type": "object", "properties": { "catalog_token": { "type": "string" }, "expires_at": { "type": "integer" }, "announce_token": { "type": "string" }, "rpc_secret": { "type": "string" } }, "required": [ "catalog_token", "expires_at" ], "additionalProperties": true }, "example": { "catalog_token": "replacement-catalog-token", "expires_at": 1788556800 } } } }, "400": { "description": "Invalid Content-Length or Invalid request body or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "invalid-request-body", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "invalid-request-body": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request-body", "title": "Invalid request body", "status": 400, "code": "invalid-request-body" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Catalog authentication required", "x-iris-problem-codes": [ "catalog-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#catalog-authentication-required", "title": "Catalog authentication required", "status": 401, "code": "catalog-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found", "x-iris-problem-codes": [ "resource-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Credential store unavailable", "x-iris-problem-codes": [ "credential-store-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "CatalogV1DevicesDeviceIdTokenRefreshRequest", "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "example": {} } } } } }, "/v1/devices/{device_id}/peer-tls": { "post": { "operationId": "catalog_post_v1_devices_device_id_peer_tls", "summary": "Enroll or renew peer TLS certificate", "description": "Enroll or renew a 24-hour peer TLS certificate using the current same-device catalog Bearer over verified HTTPS with the catalog trust provisioned during preflight. Submit a P-256 CSR; the private key stays on the device. Renew six hours before expiry. Peer TLS defaults to disabled and is configured in Console settings or at deployment for all torrents per process; this endpoint does not change the mode. Returns 409 when disabled, 429 when rate-limited, or 503 when the issuer is unavailable.", "tags": [ "catalog" ], "x-iris-service": "catalog", "x-iris-security": "deviceBearer", "servers": [ { "url": "https://iris.example:8443", "description": "Device catalog" } ], "security": [ { "deviceBearer": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" } ], "responses": { "200": { "description": "Enroll or renew peer TLS certificate response", "content": { "application/json": { "schema": { "title": "CatalogV1DevicesDeviceIdPeerTlsResponse", "type": "object", "properties": { "mode": { "type": "string" }, "certificate": { "type": "string" }, "ca": { "type": "string" }, "renew_before_seconds": { "type": "integer" }, "identity_sha256": { "type": "string" } }, "required": [ "mode", "certificate", "ca", "renew_before_seconds", "identity_sha256" ], "additionalProperties": true }, "example": { "mode": "required", "certificate": "-----BEGIN CERTIFICATE-----\n...", "ca": "-----BEGIN CERTIFICATE-----\n...", "renew_before_seconds": 21600, "identity_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } }, "400": { "description": "Invalid Content-Length or Invalid request body or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "invalid-request-body", "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid Content-Length", "status": 400, "code": "invalid-content-length" } }, "invalid-request-body": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request-body", "title": "Invalid request body", "status": 400, "code": "invalid-request-body" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Catalog authentication required", "x-iris-problem-codes": [ "catalog-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#catalog-authentication-required", "title": "Catalog authentication required", "status": 401, "code": "catalog-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "Forbidden", "x-iris-problem-codes": [ "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden" } } } }, "404": { "description": "Resource not found", "x-iris-problem-codes": [ "resource-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "411": { "description": "Content-Length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content-Length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Credential store unavailable", "x-iris-problem-codes": [ "credential-store-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "CatalogV1DevicesDeviceIdPeerTlsRequest", "type": "object", "properties": { "csr": { "type": "string" } }, "required": [ "csr" ], "additionalProperties": true }, "example": { "csr": "-----BEGIN CERTIFICATE REQUEST-----\n..." } } } } } }, "/v1/devices/{device_id}/peer-tls-revocations": { "get": { "operationId": "catalog_get_v1_devices_device_id_peer_tls_revocations", "summary": "Read current peer certificate revocations", "description": "Read the current complete peer-certificate identity deny list using the current same-device catalog Bearer over pinned HTTPS. A fresh 32-character lowercase hexadecimal nonce is required and echoed. The ASCII snapshot binds the issuing CA DER SHA256, monotonically increasing revision, issue time, five-minute expiry and at most 10,000 sorted identity hashes. Clients reject rollback and changed deny lists at the same revision; missing, invalid or expired snapshots stop peer traffic. Poll every 30 seconds.", "tags": [ "catalog" ], "x-iris-service": "catalog", "x-iris-security": "deviceBearer", "servers": [ { "url": "https://iris.example:8443", "description": "Device catalog" } ], "security": [ { "deviceBearer": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "nonce", "in": "query", "required": true, "description": "Fresh client challenge echoed by the authenticated response", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "example": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ], "responses": { "200": { "description": "CA-bound complete identity deny list, valid for five minutes", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "const": 1 }, "nonce": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "snapshot": { "type": "string", "maxLength": 1048576 } }, "required": [ "schema", "nonce", "snapshot" ], "additionalProperties": false }, "example": { "schema": 1, "nonce": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "snapshot": "IRIS-PEER-REVOCATIONS-1\nbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\n0\n1788470400\n1788470700\n" } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Catalog authentication required", "x-iris-problem-codes": [ "catalog-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#catalog-authentication-required", "title": "Catalog authentication required", "status": 401, "code": "catalog-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Resource not found", "x-iris-problem-codes": [ "resource-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-not-found", "title": "Resource not found", "status": 404, "code": "resource-not-found" } } } }, "409": { "description": "Resource conflict", "x-iris-problem-codes": [ "resource-conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#resource-conflict", "title": "Resource conflict", "status": 409, "code": "resource-conflict" } } } }, "500": { "description": "Internal server error", "x-iris-problem-codes": [ "internal-error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#internal-error", "title": "Internal server error", "status": 500, "code": "internal-error" } } } }, "503": { "description": "Credential store unavailable", "x-iris-problem-codes": [ "credential-store-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/announce": { "get": { "operationId": "tracker_get_announce", "summary": "Announce peer", "description": "Announce peer. The tracker is HTTPS-only and uses the same certificate pinned by device agents. Bearer Authorization is preferred and disables fallback. Guest Shell aria2 uses query credentials protected by TLS; BEP-compatible bencoded errors are the sole response-format exception.", "tags": [ "tracker" ], "x-iris-service": "tracker", "x-iris-security": "announceBearerOrLegacyQuery", "servers": [ { "url": "https://iris.example:6969", "description": "TLS BEP tracker v1 listener" } ], "security": [ { "announceBearer": [] }, { "legacyAnnounceToken": [] }, { "legacyTrackerKey": [] } ], "parameters": [ { "name": "info_hash", "in": "query", "required": true, "description": "Percent-encoded binary SHA-1 info hash; exactly 20 bytes after URL decoding", "schema": { "type": "string", "x-iris-decodedLength": 20 }, "example": "01234567890123456789" }, { "name": "peer_id", "in": "query", "required": false, "description": "Percent-encoded peer id; absent becomes the empty compatibility id", "schema": { "type": "string" }, "example": "-IR0001-012345678901" }, { "name": "port", "in": "query", "required": false, "description": "Listening peer port; absent defaults to 6881. An invalid port suppresses registration.", "schema": { "type": "integer", "minimum": 1, "maximum": 65535, "default": 6881 }, "example": 6881 }, { "name": "left", "in": "query", "required": false, "description": "Bytes remaining", "schema": { "type": "integer", "minimum": 0 }, "example": 1024 }, { "name": "event", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "started", "completed", "stopped" ] }, "example": "started" }, { "name": "numwant", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 50 }, "example": 50 }, { "name": "compact", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "example": 1 }, { "name": "ip", "in": "query", "required": false, "description": "Private/CGNAT IPv4 override honored only for an authenticated service principal; devices always use the socket source address", "schema": { "type": "string", "format": "ipv4" }, "example": "10.0.0.10" }, { "name": "announce_token", "in": "query", "required": false, "deprecated": true, "description": "Guest Shell-only credential fallback. Bearer Authorization takes precedence and disables query fallback.", "schema": { "type": "string", "writeOnly": true } }, { "name": "key", "in": "query", "required": false, "deprecated": true, "description": "Query credential accepted only when Authorization is absent.", "schema": { "type": "string", "writeOnly": true } } ], "responses": { "200": { "description": "BEP 3 bencoded tracker response", "content": { "text/plain": { "schema": {}, "example": "d8:intervali30ee" } } }, "400": { "description": "BEP-compatible bencoded failure; deliberate RFC 9457 exception", "content": { "text/plain": { "schema": {}, "example": "d14:failure reason23:invalid tracker requeste" } } }, "401": { "description": "BEP-compatible bencoded failure; deliberate RFC 9457 exception", "content": { "text/plain": { "schema": {}, "example": "d14:failure reason23:authentication requirede" } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge for the preferred header transport", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } } }, "403": { "description": "BEP-compatible bencoded failure; deliberate RFC 9457 exception", "content": { "text/plain": { "schema": {}, "example": "d14:failure reason23:authentication requirede" } } }, "404": { "description": "BEP-compatible bencoded failure; deliberate RFC 9457 exception", "content": { "text/plain": { "schema": {}, "example": "d14:failure reason17:torrent not founde" } } }, "503": { "description": "BEP-compatible bencoded failure; deliberate RFC 9457 exception", "content": { "text/plain": { "schema": {}, "example": "d14:failure reason28:credential store unavailablee" } }, "headers": { "Retry-After": { "description": "Seconds before retrying an unavailable credential store", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } } } } } }, "/scrape": { "get": { "operationId": "tracker_get_scrape", "summary": "Scrape torrent", "description": "Scrape torrent. The tracker is HTTPS-only and uses the same certificate pinned by device agents. Bearer Authorization is preferred and disables fallback. Guest Shell aria2 uses query credentials protected by TLS; BEP-compatible bencoded errors are the sole response-format exception. A device principal may scrape only an info hash in its current catalog assignment; unknown and cross-assignment hashes return the same result. The seeder service and authenticated unattributed principals can scrape all torrents.", "tags": [ "tracker" ], "x-iris-service": "tracker", "x-iris-security": "announceBearerOrLegacyQuery", "servers": [ { "url": "https://iris.example:6969", "description": "TLS BEP tracker v1 listener" } ], "security": [ { "announceBearer": [] }, { "legacyAnnounceToken": [] }, { "legacyTrackerKey": [] } ], "parameters": [ { "name": "info_hash", "in": "query", "required": true, "description": "Percent-encoded binary SHA-1 info hash; exactly 20 bytes after URL decoding", "schema": { "type": "string", "x-iris-decodedLength": 20 }, "example": "01234567890123456789" }, { "name": "announce_token", "in": "query", "required": false, "deprecated": true, "description": "Guest Shell-only credential fallback. Bearer Authorization takes precedence and disables query fallback.", "schema": { "type": "string", "writeOnly": true } }, { "name": "key", "in": "query", "required": false, "deprecated": true, "description": "Query credential accepted only when Authorization is absent.", "schema": { "type": "string", "writeOnly": true } } ], "responses": { "200": { "description": "BEP 3 bencoded tracker response", "content": { "text/plain": { "schema": {}, "example": "d8:intervali30ee" } } }, "400": { "description": "BEP-compatible bencoded failure; deliberate RFC 9457 exception", "content": { "text/plain": { "schema": {}, "example": "d14:failure reason23:invalid tracker requeste" } } }, "401": { "description": "BEP-compatible bencoded failure; deliberate RFC 9457 exception", "content": { "text/plain": { "schema": {}, "example": "d14:failure reason23:authentication requirede" } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge for the preferred header transport", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } } }, "403": { "description": "BEP-compatible bencoded failure; deliberate RFC 9457 exception", "content": { "text/plain": { "schema": {}, "example": "d14:failure reason23:authentication requirede" } } }, "404": { "description": "BEP-compatible bencoded failure; deliberate RFC 9457 exception", "content": { "text/plain": { "schema": {}, "example": "d14:failure reason17:torrent not founde" } } }, "503": { "description": "BEP-compatible bencoded failure; deliberate RFC 9457 exception", "content": { "text/plain": { "schema": {}, "example": "d14:failure reason28:credential store unavailablee" } }, "headers": { "Retry-After": { "description": "Seconds before retrying an unavailable credential store", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } } } } } }, "/metrics": { "get": { "operationId": "telemetry_get_metrics", "summary": "Read Prometheus metrics", "description": "Read Prometheus metrics.", "tags": [ "telemetry" ], "x-iris-service": "telemetry", "x-iris-security": "observabilityBearer", "servers": [ { "url": "https://iris.example:9101", "description": "TLS telemetry listener" } ], "security": [ { "observabilityBearer": [] } ], "parameters": [], "responses": { "200": { "description": "Prometheus text exposition", "content": { "text/plain": { "schema": { "type": "string" }, "example": "iris_tracker_peers 2\n" } } }, "401": { "description": "Observability authentication required", "x-iris-problem-codes": [ "observability-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#observability-authentication-required", "title": "Observability authentication required", "status": 401, "code": "observability-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } } }, "/swarm": { "get": { "operationId": "telemetry_get_swarm", "summary": "Read swarm state", "description": "Read swarm state. Image rows include image_id when the torrent hash maps to one catalog image. Observations and reports carry image_id when known; match it before attributing measurements. Tracker seeder role does not establish device staging completion, and ambiguous peer rates remain unavailable.", "tags": [ "telemetry" ], "x-iris-service": "telemetry", "x-iris-security": "managementBearer", "servers": [ { "url": "https://iris.example:9101", "description": "TLS telemetry listener" } ], "security": [ { "managementBearer": [] } ], "parameters": [], "responses": { "200": { "description": "Whole swarm or an empty serialization fallback", "content": { "application/json": { "schema": { "oneOf": [ { "title": "TelemetrySwarmWholeResponse", "type": "object", "properties": { "now": { "type": "number" }, "server": { "title": "TelemetrySwarmWholeResponseServer", "type": "object", "properties": { "host": { "type": "string" }, "server_observation": { "title": "TelemetrySwarmWholeResponseServerServer_Observation", "type": "object", "properties": { "observed_at": { "type": [ "number", "null" ] }, "rpc_up": { "type": "boolean" }, "unavailable": { "type": "boolean" }, "aria_session_id": { "type": [ "string", "null" ] }, "peer_tls": { "type": "object", "additionalProperties": false, "required": [ "runtime_mode", "runtime_source" ], "properties": { "runtime_mode": { "enum": [ "disabled", "required", "unknown" ] }, "runtime_source": { "enum": [ "aria2_rpc", "unknown" ] }, "revocations": { "type": "object", "properties": { "supported": { "const": true }, "mode": { "enum": [ "required", "disabled" ] }, "state": { "enum": [ "valid", "unavailable", "expired" ] }, "authority": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "issued_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "expires_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "own_revoked": { "type": "boolean" }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "supported", "mode", "state", "authority", "revision", "issued_at", "expires_at", "own_revoked", "observed_at" ], "additionalProperties": false }, "reported_at": { "type": [ "number", "null" ] } }, "description": "Last reported torrent TLS daemon policy, not negotiated connection evidence. Missing means unknown." } }, "required": [ "observed_at", "rpc_up", "unavailable", "aria_session_id" ], "additionalProperties": true } }, "required": [ "host", "server_observation" ], "additionalProperties": true }, "images": { "type": "array", "items": { "title": "TelemetrySwarmWholeResponseImagesItem", "type": "object", "properties": { "image": { "type": "string" }, "info_hash": { "type": "string" }, "total_bytes": { "type": [ "integer", "null" ] }, "seeders": { "type": "integer" }, "leechers": { "type": "integer" }, "peers": { "type": "array", "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "ip", "port", "tracker", "device_id" ], "properties": { "ip": { "type": "string" }, "port": { "type": "integer" }, "tracker": { "type": "object", "additionalProperties": false, "required": [ "principal_type", "role", "left", "last_seen", "progress", "principal_id" ], "properties": { "principal_type": { "const": "device" }, "role": { "enum": [ "seeder", "leecher" ] }, "left": { "type": [ "integer", "null" ] }, "last_seen": { "type": [ "number", "null" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "principal_id": { "type": "string" } } }, "device_observation": { "type": "object" }, "server_observation": { "type": "object" }, "latest_report": { "type": "object" }, "peer_policy": { "type": "object" }, "peer_enforcement": { "type": "object" }, "device_id": { "type": "string" }, "peer_tls": { "type": "object", "additionalProperties": false, "required": [ "configured_mode", "runtime_mode", "runtime_source" ], "properties": { "configured_mode": { "enum": [ "disabled", "required" ] }, "runtime_mode": { "enum": [ "disabled", "required", "unknown" ] }, "runtime_source": { "enum": [ "aria2_rpc", "unknown" ] }, "revocations": { "type": "object", "properties": { "supported": { "const": true }, "mode": { "enum": [ "required", "disabled" ] }, "state": { "enum": [ "valid", "unavailable", "expired" ] }, "authority": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "issued_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "expires_at": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "own_revoked": { "type": "boolean" }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "supported", "mode", "state", "authority", "revision", "issued_at", "expires_at", "own_revoked", "observed_at" ], "additionalProperties": false }, "reported_at": { "type": [ "number", "null" ] } }, "description": "Last reported torrent TLS daemon policy, not negotiated connection evidence. Missing means unknown." }, "peer_telemetry": { "type": "object", "additionalProperties": false, "properties": { "supported": { "type": "boolean" }, "requested_interval_s": { "enum": [ 10, 60, null ] }, "effective_interval_s": { "type": [ "integer", "null" ] } } }, "model": { "type": "string" }, "current_image_id": { "type": "string" }, "stage_state": { "type": "string" }, "staged_image_ids": { "type": "array", "items": { "type": "string" } }, "errored_image_ids": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": [ "ip", "port", "tracker" ], "properties": { "ip": { "type": "string" }, "port": { "type": "integer" }, "tracker": { "type": "object", "additionalProperties": false, "required": [ "principal_type", "role", "left", "last_seen", "progress", "principal_id" ], "properties": { "principal_type": { "const": "service" }, "role": { "enum": [ "seeder", "leecher" ] }, "left": { "type": [ "integer", "null" ] }, "last_seen": { "type": [ "number", "null" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "principal_id": { "type": "string" } } }, "device_observation": { "type": "object" }, "server_observation": { "type": "object" }, "latest_report": { "type": "object" }, "peer_policy": { "type": "object" }, "peer_enforcement": { "type": "object" } } }, { "type": "object", "additionalProperties": false, "required": [ "ip", "port", "tracker" ], "properties": { "ip": { "type": "string" }, "port": { "type": "integer" }, "tracker": { "type": "object", "additionalProperties": false, "required": [ "principal_type", "role", "left", "last_seen", "progress" ], "properties": { "principal_type": { "const": "legacy" }, "role": { "enum": [ "seeder", "leecher" ] }, "left": { "type": [ "integer", "null" ] }, "last_seen": { "type": [ "number", "null" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "participant_class": { "type": "string" } } }, "device_id": { "type": "null" }, "warning": { "const": "legacy_unattributed" }, "quarantine_available": { "const": false } } } ] } }, "peer_edges": { "type": "array", "maxItems": 1024, "items": { "type": "object", "properties": { "source_device_id": { "type": "string" }, "target_device_id": { "type": "string" }, "reporter_device_id": { "type": "string" }, "bytes_per_second": { "type": "integer", "minimum": 1 }, "connection_count": { "type": "integer", "minimum": 1, "maximum": 32 }, "rate_field": { "enum": [ "send_bps", "receive_bps" ] }, "identity_basis": { "enum": [ "tracker_endpoint", "unique_tracker_address" ] }, "received_at": { "type": "number" }, "observed_at": { "type": [ "number", "null" ] }, "age_s": { "type": "integer", "minimum": 0 }, "valid_for_s": { "type": "integer", "minimum": 1, "maximum": 120 } }, "required": [ "source_device_id", "target_device_id", "reporter_device_id", "bytes_per_second", "connection_count", "rate_field", "identity_basis", "received_at", "observed_at", "age_s", "valid_for_s" ], "additionalProperties": false } }, "peer_edges_truncated": { "type": "boolean" }, "unattributed_peer_connections": { "type": "integer", "minimum": 0 } }, "required": [ "image", "info_hash", "total_bytes", "seeders", "leechers", "peers" ], "additionalProperties": true } } }, "required": [ "now", "server", "images" ], "additionalProperties": false }, { "type": "object", "maxProperties": 0 } ] }, "examples": { "whole": { "value": { "now": 1788470400.0, "server": { "host": "192.0.2.1", "server_observation": { "observed_at": 1788470400, "rpc_up": true, "unavailable": false, "aria_session_id": "session-01" } }, "images": [ { "image": "image.bin", "info_hash": "0000000000000000000000000000000000000000", "total_bytes": 1048576, "seeders": 1, "leechers": 0, "peers": [ { "device_id": "edge-01", "ip": "192.0.2.10", "port": 6881, "tracker": { "principal_type": "device", "principal_id": "edge-01", "role": "seeder", "left": 0, "last_seen": 1788470400.0, "progress": 1.0 } } ] } ] } }, "serializationFallback": { "value": {} } } } } }, "401": { "description": "Management authentication required", "x-iris-problem-codes": [ "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } } } } }, "/status": { "get": { "operationId": "telemetry_get_status", "summary": "Read detailed telemetry status", "description": "Read detailed telemetry status.", "tags": [ "telemetry" ], "x-iris-service": "telemetry", "x-iris-security": "managementBearer", "servers": [ { "url": "https://iris.example:9101", "description": "TLS telemetry listener" } ], "security": [ { "managementBearer": [] } ], "parameters": [], "responses": { "200": { "description": "Read detailed telemetry status response", "content": { "application/json": { "schema": { "title": "TelemetryStatusResponse", "type": "object", "properties": { "ok": { "type": "boolean" }, "otlp_export": { "title": "TelemetryStatusResponseOtlp_Export", "type": "object", "properties": { "state": { "type": "string" }, "signals": { "title": "TelemetryStatusResponseOtlp_ExportSignals", "type": "object", "properties": {}, "required": [], "additionalProperties": true } }, "required": [ "state", "signals" ], "additionalProperties": true } }, "required": [ "ok", "otlp_export" ], "additionalProperties": true }, "example": { "ok": true, "otlp_export": { "state": "healthy", "signals": {} } } } } }, "401": { "description": "Management authentication required", "x-iris-problem-codes": [ "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "503": { "description": "Telemetry status unavailable", "x-iris-problem-codes": [ "telemetry-status-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#telemetry-status-unavailable", "title": "Telemetry status unavailable", "status": 503, "code": "telemetry-status-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/v1/devices/{device_id}/artifacts/{artifact_path}": { "get": { "operationId": "artifact_get_v1_devices_device_id_artifacts_artifact_path", "summary": "Download device artifact", "description": "Download device artifact. HTTP Basic username is device_id and password is that same device's current/overlap catalog token; authentication precedes path translation and existence checks.", "tags": [ "artifact" ], "x-iris-service": "artifact", "x-iris-security": "artifactBasic", "servers": [ { "url": "https://iris.example:8000", "description": "Artifact service" } ], "security": [ { "artifactBasic": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "artifact_path", "in": "path", "required": true, "description": "Slash-separated path below the authenticated device artifact root", "schema": { "type": "string", "minLength": 1 }, "example": "iris-agent.tgz" } ], "responses": { "200": { "description": "Artifact bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Present whenever the resolved artifact is under staging" } }, "content": { "application/octet-stream": { "schema": {}, "example": "" } } }, "304": { "description": "Artifact has not changed since If-Modified-Since" }, "401": { "description": "Artifact authentication required", "x-iris-problem-codes": [ "artifact-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-authentication-required", "title": "Artifact authentication required", "status": 401, "code": "artifact-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Basic realm=\"iris-artifacts\", charset=\"UTF-8\"" } } }, "403": { "description": "Artifact resource forbidden or Artifact forbidden", "x-iris-problem-codes": [ "artifact-resource-forbidden", "artifact-forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "artifact-resource-forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-resource-forbidden", "title": "Artifact resource forbidden", "status": 403, "code": "artifact-resource-forbidden" } }, "artifact-forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-forbidden", "title": "Artifact forbidden", "status": 403, "code": "artifact-forbidden" } } } } } }, "404": { "description": "Artifact not found", "x-iris-problem-codes": [ "artifact-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-not-found", "title": "Artifact not found", "status": 404, "code": "artifact-not-found" } } } }, "500": { "description": "Artifact request failed", "x-iris-problem-codes": [ "artifact-request-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-request-failed", "title": "Artifact request failed", "status": 500, "code": "artifact-request-failed" } } } }, "503": { "description": "Credential store unavailable", "x-iris-problem-codes": [ "credential-store-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "head": { "operationId": "artifact_head_v1_devices_device_id_artifacts_artifact_path", "summary": "Inspect device artifact", "description": "Inspect device artifact. HTTP Basic username is device_id and password is that same device's current/overlap catalog token; authentication precedes path translation and existence checks.", "tags": [ "artifact" ], "x-iris-service": "artifact", "x-iris-security": "artifactBasic", "servers": [ { "url": "https://iris.example:8000", "description": "Artifact service" } ], "security": [ { "artifactBasic": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "minLength": 1 }, "example": "edge-01" }, { "name": "artifact_path", "in": "path", "required": true, "description": "Slash-separated path below the authenticated device artifact root", "schema": { "type": "string", "minLength": 1 }, "example": "iris-agent.tgz" } ], "responses": { "200": { "description": "Artifact metadata", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Present whenever the resolved artifact is under staging" } } }, "304": { "description": "Artifact has not changed since If-Modified-Since" }, "401": { "description": "Artifact authentication required", "x-iris-problem-codes": [ "artifact-authentication-required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-authentication-required", "title": "Artifact authentication required", "status": 401, "code": "artifact-authentication-required" } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Basic realm=\"iris-artifacts\", charset=\"UTF-8\"" } } }, "403": { "description": "Artifact resource forbidden or Artifact forbidden", "x-iris-problem-codes": [ "artifact-resource-forbidden", "artifact-forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "artifact-resource-forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-resource-forbidden", "title": "Artifact resource forbidden", "status": 403, "code": "artifact-resource-forbidden" } }, "artifact-forbidden": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-forbidden", "title": "Artifact forbidden", "status": 403, "code": "artifact-forbidden" } } } } } }, "404": { "description": "Artifact not found", "x-iris-problem-codes": [ "artifact-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-not-found", "title": "Artifact not found", "status": 404, "code": "artifact-not-found" } } } }, "500": { "description": "Artifact request failed", "x-iris-problem-codes": [ "artifact-request-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-request-failed", "title": "Artifact request failed", "status": 500, "code": "artifact-request-failed" } } } }, "503": { "description": "Credential store unavailable", "x-iris-problem-codes": [ "credential-store-unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/bootstrap.sh": { "get": { "operationId": "artifact_get_bootstrap_sh", "summary": "Download Guest Shell bootstrap", "description": "Download Guest Shell bootstrap. Guest Shell can fetch an exact static allowlist containing no credentials anonymously; arbitrary files are unreachable.", "tags": [ "artifact" ], "x-iris-service": "artifact", "x-iris-security": "guestShellAnonymousStatic", "servers": [ { "url": "https://iris.example:8000", "description": "Artifact service" } ], "security": [], "parameters": [], "responses": { "200": { "description": "Artifact bytes", "headers": { "Deprecation": { "schema": { "type": "boolean", "const": true }, "description": "Present on the Guest Shell compatibility surface" } }, "content": { "application/octet-stream": { "schema": {}, "example": "" } } }, "304": { "description": "Artifact has not changed since If-Modified-Since" }, "404": { "description": "Artifact not found", "x-iris-problem-codes": [ "artifact-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-not-found", "title": "Artifact not found", "status": 404, "code": "artifact-not-found" } } } }, "500": { "description": "Artifact request failed", "x-iris-problem-codes": [ "artifact-request-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-request-failed", "title": "Artifact request failed", "status": 500, "code": "artifact-request-failed" } } } } } }, "head": { "operationId": "artifact_head_bootstrap_sh", "summary": "Inspect Guest Shell bootstrap", "description": "Inspect Guest Shell bootstrap. Guest Shell can fetch an exact static allowlist containing no credentials anonymously; arbitrary files are unreachable.", "tags": [ "artifact" ], "x-iris-service": "artifact", "x-iris-security": "guestShellAnonymousStatic", "servers": [ { "url": "https://iris.example:8000", "description": "Artifact service" } ], "security": [], "parameters": [], "responses": { "200": { "description": "Artifact metadata", "headers": { "Deprecation": { "schema": { "type": "boolean", "const": true }, "description": "Present on the Guest Shell compatibility surface" } } }, "304": { "description": "Artifact has not changed since If-Modified-Since" }, "404": { "description": "Artifact not found", "x-iris-problem-codes": [ "artifact-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-not-found", "title": "Artifact not found", "status": 404, "code": "artifact-not-found" } } } }, "500": { "description": "Artifact request failed", "x-iris-problem-codes": [ "artifact-request-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-request-failed", "title": "Artifact request failed", "status": 500, "code": "artifact-request-failed" } } } } } } }, "/iris-agent.tgz": { "get": { "operationId": "artifact_get_iris_agent_tgz", "summary": "Download x86 Guest Shell agent", "description": "Download x86 Guest Shell agent. Guest Shell can fetch an exact static allowlist containing no credentials anonymously; arbitrary files are unreachable.", "tags": [ "artifact" ], "x-iris-service": "artifact", "x-iris-security": "guestShellAnonymousStatic", "servers": [ { "url": "https://iris.example:8000", "description": "Artifact service" } ], "security": [], "parameters": [], "responses": { "200": { "description": "Artifact bytes", "headers": { "Deprecation": { "schema": { "type": "boolean", "const": true }, "description": "Present on the Guest Shell compatibility surface" } }, "content": { "application/octet-stream": { "schema": {}, "example": "" } } }, "304": { "description": "Artifact has not changed since If-Modified-Since" }, "404": { "description": "Artifact not found", "x-iris-problem-codes": [ "artifact-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-not-found", "title": "Artifact not found", "status": 404, "code": "artifact-not-found" } } } }, "500": { "description": "Artifact request failed", "x-iris-problem-codes": [ "artifact-request-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-request-failed", "title": "Artifact request failed", "status": 500, "code": "artifact-request-failed" } } } } } }, "head": { "operationId": "artifact_head_iris_agent_tgz", "summary": "Inspect x86 Guest Shell agent", "description": "Inspect x86 Guest Shell agent. Guest Shell can fetch an exact static allowlist containing no credentials anonymously; arbitrary files are unreachable.", "tags": [ "artifact" ], "x-iris-service": "artifact", "x-iris-security": "guestShellAnonymousStatic", "servers": [ { "url": "https://iris.example:8000", "description": "Artifact service" } ], "security": [], "parameters": [], "responses": { "200": { "description": "Artifact metadata", "headers": { "Deprecation": { "schema": { "type": "boolean", "const": true }, "description": "Present on the Guest Shell compatibility surface" } } }, "304": { "description": "Artifact has not changed since If-Modified-Since" }, "404": { "description": "Artifact not found", "x-iris-problem-codes": [ "artifact-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-not-found", "title": "Artifact not found", "status": 404, "code": "artifact-not-found" } } } }, "500": { "description": "Artifact request failed", "x-iris-problem-codes": [ "artifact-request-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-request-failed", "title": "Artifact request failed", "status": 500, "code": "artifact-request-failed" } } } } } } }, "/iris-agent-arm.tgz": { "get": { "operationId": "artifact_get_iris_agent_arm_tgz", "summary": "Download ARM Guest Shell agent", "description": "Download ARM Guest Shell agent. Guest Shell can fetch an exact static allowlist containing no credentials anonymously; arbitrary files are unreachable.", "tags": [ "artifact" ], "x-iris-service": "artifact", "x-iris-security": "guestShellAnonymousStatic", "servers": [ { "url": "https://iris.example:8000", "description": "Artifact service" } ], "security": [], "parameters": [], "responses": { "200": { "description": "Artifact bytes", "headers": { "Deprecation": { "schema": { "type": "boolean", "const": true }, "description": "Present on the Guest Shell compatibility surface" } }, "content": { "application/octet-stream": { "schema": {}, "example": "" } } }, "304": { "description": "Artifact has not changed since If-Modified-Since" }, "404": { "description": "Artifact not found", "x-iris-problem-codes": [ "artifact-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-not-found", "title": "Artifact not found", "status": 404, "code": "artifact-not-found" } } } }, "500": { "description": "Artifact request failed", "x-iris-problem-codes": [ "artifact-request-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-request-failed", "title": "Artifact request failed", "status": 500, "code": "artifact-request-failed" } } } } } }, "head": { "operationId": "artifact_head_iris_agent_arm_tgz", "summary": "Inspect ARM Guest Shell agent", "description": "Inspect ARM Guest Shell agent. Guest Shell can fetch an exact static allowlist containing no credentials anonymously; arbitrary files are unreachable.", "tags": [ "artifact" ], "x-iris-service": "artifact", "x-iris-security": "guestShellAnonymousStatic", "servers": [ { "url": "https://iris.example:8000", "description": "Artifact service" } ], "security": [], "parameters": [], "responses": { "200": { "description": "Artifact metadata", "headers": { "Deprecation": { "schema": { "type": "boolean", "const": true }, "description": "Present on the Guest Shell compatibility surface" } } }, "304": { "description": "Artifact has not changed since If-Modified-Since" }, "404": { "description": "Artifact not found", "x-iris-problem-codes": [ "artifact-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-not-found", "title": "Artifact not found", "status": 404, "code": "artifact-not-found" } } } }, "500": { "description": "Artifact request failed", "x-iris-problem-codes": [ "artifact-request-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-request-failed", "title": "Artifact request failed", "status": 500, "code": "artifact-request-failed" } } } } } } }, "/iris-catalog.pem": { "get": { "operationId": "artifact_get_iris_catalog_pem", "summary": "Download Guest Shell catalog CA", "description": "Download Guest Shell catalog CA. Guest Shell can fetch an exact static allowlist containing no credentials anonymously; arbitrary files are unreachable.", "tags": [ "artifact" ], "x-iris-service": "artifact", "x-iris-security": "guestShellAnonymousStatic", "servers": [ { "url": "https://iris.example:8000", "description": "Artifact service" } ], "security": [], "parameters": [], "responses": { "200": { "description": "Artifact bytes", "headers": { "Deprecation": { "schema": { "type": "boolean", "const": true }, "description": "Present on the Guest Shell compatibility surface" } }, "content": { "application/octet-stream": { "schema": {}, "example": "" } } }, "304": { "description": "Artifact has not changed since If-Modified-Since" }, "404": { "description": "Artifact not found", "x-iris-problem-codes": [ "artifact-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-not-found", "title": "Artifact not found", "status": 404, "code": "artifact-not-found" } } } }, "500": { "description": "Artifact request failed", "x-iris-problem-codes": [ "artifact-request-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-request-failed", "title": "Artifact request failed", "status": 500, "code": "artifact-request-failed" } } } } } }, "head": { "operationId": "artifact_head_iris_catalog_pem", "summary": "Inspect Guest Shell catalog CA", "description": "Inspect Guest Shell catalog CA. Guest Shell can fetch an exact static allowlist containing no credentials anonymously; arbitrary files are unreachable.", "tags": [ "artifact" ], "x-iris-service": "artifact", "x-iris-security": "guestShellAnonymousStatic", "servers": [ { "url": "https://iris.example:8000", "description": "Artifact service" } ], "security": [], "parameters": [], "responses": { "200": { "description": "Artifact metadata", "headers": { "Deprecation": { "schema": { "type": "boolean", "const": true }, "description": "Present on the Guest Shell compatibility surface" } } }, "304": { "description": "Artifact has not changed since If-Modified-Since" }, "404": { "description": "Artifact not found", "x-iris-problem-codes": [ "artifact-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-not-found", "title": "Artifact not found", "status": 404, "code": "artifact-not-found" } } } }, "500": { "description": "Artifact request failed", "x-iris-problem-codes": [ "artifact-request-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-request-failed", "title": "Artifact request failed", "status": 500, "code": "artifact-request-failed" } } } } } } }, "/iris-signers.pem": { "get": { "operationId": "artifact_get_iris_signers_pem", "summary": "Download Guest Shell instruction signer trust", "description": "Download Guest Shell instruction signer trust. Guest Shell can fetch an exact static allowlist containing no credentials anonymously; arbitrary files are unreachable.", "tags": [ "artifact" ], "x-iris-service": "artifact", "x-iris-security": "guestShellAnonymousStatic", "servers": [ { "url": "https://iris.example:8000", "description": "Artifact service" } ], "security": [], "parameters": [], "responses": { "200": { "description": "Artifact bytes", "headers": { "Deprecation": { "schema": { "type": "boolean", "const": true }, "description": "Present on the Guest Shell compatibility surface" } }, "content": { "application/octet-stream": { "schema": {}, "example": "" } } }, "304": { "description": "Artifact has not changed since If-Modified-Since" }, "404": { "description": "Artifact not found", "x-iris-problem-codes": [ "artifact-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-not-found", "title": "Artifact not found", "status": 404, "code": "artifact-not-found" } } } }, "500": { "description": "Artifact request failed", "x-iris-problem-codes": [ "artifact-request-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-request-failed", "title": "Artifact request failed", "status": 500, "code": "artifact-request-failed" } } } } } }, "head": { "operationId": "artifact_head_iris_signers_pem", "summary": "Inspect Guest Shell instruction signer trust", "description": "Inspect Guest Shell instruction signer trust. Guest Shell can fetch an exact static allowlist containing no credentials anonymously; arbitrary files are unreachable.", "tags": [ "artifact" ], "x-iris-service": "artifact", "x-iris-security": "guestShellAnonymousStatic", "servers": [ { "url": "https://iris.example:8000", "description": "Artifact service" } ], "security": [], "parameters": [], "responses": { "200": { "description": "Artifact metadata", "headers": { "Deprecation": { "schema": { "type": "boolean", "const": true }, "description": "Present on the Guest Shell compatibility surface" } } }, "304": { "description": "Artifact has not changed since If-Modified-Since" }, "404": { "description": "Artifact not found", "x-iris-problem-codes": [ "artifact-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-not-found", "title": "Artifact not found", "status": 404, "code": "artifact-not-found" } } } }, "500": { "description": "Artifact request failed", "x-iris-problem-codes": [ "artifact-request-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-request-failed", "title": "Artifact request failed", "status": 500, "code": "artifact-request-failed" } } } } } } }, "/staging/{legacy_artifact}": { "get": { "operationId": "artifact_get_staging_legacy_artifact", "summary": "Download Guest Shell enrollment capability", "description": "Download Guest Shell enrollment capability. Guest Shell uses IOS copy HTTPS with staging filenames that are 128-bit time-bounded capabilities. Explicit artifact API clients use resource-bound Basic authentication.", "tags": [ "artifact" ], "x-iris-service": "artifact", "x-iris-security": "legacyGuestShell", "servers": [ { "url": "https://iris.example:8000", "description": "Artifact service" } ], "security": [], "parameters": [ { "name": "legacy_artifact", "in": "path", "required": true, "description": "High-entropy, time-bounded Guest Shell enrollment filename", "schema": { "type": "string", "oneOf": [ { "pattern": "^iris-agent-[A-Za-z0-9._:-]+-[0-9A-Fa-f]{32}\\.conf$" }, { "pattern": "^rpc-secret-[0-9A-Fa-f]{32}$" }, { "pattern": "^iris-instructions-[A-Za-z0-9._:-]+-[0-9a-f]{32}\\.envelope$" }, { "pattern": "^bundle-sha256-[0-9a-f]{32}$" } ] }, "example": "iris-agent-edge-01-0123456789abcdef0123456789abcdef.conf" } ], "responses": { "200": { "description": "Artifact bytes", "headers": { "Deprecation": { "schema": { "type": "boolean", "const": true }, "description": "Present on the Guest Shell compatibility surface" }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Present whenever the resolved artifact is under staging" } }, "content": { "application/octet-stream": { "schema": {}, "example": "" } } }, "304": { "description": "Artifact has not changed since If-Modified-Since" }, "403": { "description": "Artifact forbidden", "x-iris-problem-codes": [ "artifact-forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-forbidden", "title": "Artifact forbidden", "status": 403, "code": "artifact-forbidden" } } } }, "404": { "description": "Artifact not found", "x-iris-problem-codes": [ "artifact-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-not-found", "title": "Artifact not found", "status": 404, "code": "artifact-not-found" } } } }, "500": { "description": "Artifact request failed", "x-iris-problem-codes": [ "artifact-request-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-request-failed", "title": "Artifact request failed", "status": 500, "code": "artifact-request-failed" } } } } }, "x-iris-path-capability": { "parameter": "legacy_artifact", "entropyBits": 128, "timeBounded": true, "compatibility": "Guest Shell copy HTTPS" } }, "head": { "operationId": "artifact_head_staging_legacy_artifact", "summary": "Inspect Guest Shell enrollment capability", "description": "Inspect Guest Shell enrollment capability. Guest Shell uses IOS copy HTTPS with staging filenames that are 128-bit time-bounded capabilities. Explicit artifact API clients use resource-bound Basic authentication.", "tags": [ "artifact" ], "x-iris-service": "artifact", "x-iris-security": "legacyGuestShell", "servers": [ { "url": "https://iris.example:8000", "description": "Artifact service" } ], "security": [], "parameters": [ { "name": "legacy_artifact", "in": "path", "required": true, "description": "High-entropy, time-bounded Guest Shell enrollment filename", "schema": { "type": "string", "oneOf": [ { "pattern": "^iris-agent-[A-Za-z0-9._:-]+-[0-9A-Fa-f]{32}\\.conf$" }, { "pattern": "^rpc-secret-[0-9A-Fa-f]{32}$" }, { "pattern": "^iris-instructions-[A-Za-z0-9._:-]+-[0-9a-f]{32}\\.envelope$" }, { "pattern": "^bundle-sha256-[0-9a-f]{32}$" } ] }, "example": "iris-agent-edge-01-0123456789abcdef0123456789abcdef.conf" } ], "responses": { "200": { "description": "Artifact metadata", "headers": { "Deprecation": { "schema": { "type": "boolean", "const": true }, "description": "Present on the Guest Shell compatibility surface" }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Present whenever the resolved artifact is under staging" } } }, "304": { "description": "Artifact has not changed since If-Modified-Since" }, "403": { "description": "Artifact forbidden", "x-iris-problem-codes": [ "artifact-forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-forbidden", "title": "Artifact forbidden", "status": 403, "code": "artifact-forbidden" } } } }, "404": { "description": "Artifact not found", "x-iris-problem-codes": [ "artifact-not-found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-not-found", "title": "Artifact not found", "status": 404, "code": "artifact-not-found" } } } }, "500": { "description": "Artifact request failed", "x-iris-problem-codes": [ "artifact-request-failed" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#artifact-request-failed", "title": "Artifact request failed", "status": 500, "code": "artifact-request-failed" } } } } }, "x-iris-path-capability": { "parameter": "legacy_artifact", "entropyBits": 128, "timeBounded": true, "compatibility": "Guest Shell copy HTTPS" } } }, "/api/v1/schedules": { "get": { "operationId": "console_get_api_v1_schedules", "summary": "List schedules", "description": "List schedules. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "All schedules; each row includes its own ETag, with no collection ETag", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedules": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleView" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } }, "required": [ "schedules", "total" ], "additionalProperties": false }, "example": { "schedules": [ { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "etag": "\"iris-schedule-s-boat-1\"", "creator_exists": true, "next_fire": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "future", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null } } ], "total": 1 } } } }, "400": { "description": "Invalid content length or Request body not supported", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-content-length" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "request-body-not-supported" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required" }, "title": { "type": "string" }, "status": { "const": 411 }, "code": { "const": "content-length-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large" }, "title": { "type": "string" }, "status": { "const": 413 }, "code": { "const": "payload-too-large" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid schedule", "x-iris-problem-codes": [ "invalid_schedule" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Management api unavailable or Schedule state unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "management-api-unavailable", "schedule_state_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "management-api-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "console_post_api_v1_schedules", "summary": "Create a schedule", "description": "Create a schedule. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:. Create-if-absent: the caller selects id; a duplicate returns 409 schedule_conflict. The server supplies generation, revision, creator, creation time and target preview. No If-Match or process-local Idempotency-Key replay is required; inspect the selected id after an uncertain retry.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "201": { "description": "Saved schedule view with server-owned identity and preview", "headers": { "ETag": { "description": "Strong ETag of the returned schedule revision", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" }, "Location": { "description": "Versioned resource path of the created schedule", "schema": { "type": "string", "format": "uri-reference" }, "example": "/api/v1/schedules/s-boat" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/ScheduleView" }, "target_facts": { "type": "object", "properties": { "missing_os_family": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "role_drift": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "quarantined_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } } }, "required": [ "missing_os_family", "role_drift", "quarantined_ids" ], "additionalProperties": false } }, "required": [ "schedule", "target_facts" ], "additionalProperties": false }, "example": { "schedule": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "etag": "\"iris-schedule-s-boat-1\"", "creator_exists": true, "next_fire": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "future", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null } }, "target_facts": { "missing_os_family": 0, "role_drift": 0, "quarantined_ids": [] } } } } }, "400": { "description": "Invalid content length or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "invalid-request" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-content-length" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-request" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed" }, "title": { "type": "string" }, "status": { "const": 403 }, "code": { "const": "csrf-validation-failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "409": { "description": "Schedule conflict", "x-iris-problem-codes": [ "schedule_conflict" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_conflict" }, "title": { "type": "string" }, "status": { "const": 409 }, "code": { "const": "schedule_conflict" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_conflict", "title": "Schedule conflict", "status": 409, "code": "schedule_conflict" } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required" }, "title": { "type": "string" }, "status": { "const": 411 }, "code": { "const": "content-length-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large" }, "title": { "type": "string" }, "status": { "const": 413 }, "code": { "const": "payload-too-large" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid schedule or Role not found", "x-iris-problem-codes": [ "invalid_schedule", "role_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "role_not_found" }, "role": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,31}$", "not": { "enum": [ "default", "legacy", "origin", "quarantine", "seeder" ] } } }, "required": [ "type", "title", "status", "code", "role" ], "additionalProperties": false } ] }, "examples": { "invalid_schedule": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } }, "role_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found", "title": "Role not found", "status": 422, "code": "role_not_found", "role": "boat" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Management api unavailable or Policy error or Policy fail closed or Schedule state unavailable or Schedule target heartbeat unavailable or Schedule target policy unavailable or Schedule target status unavailable or Schedule target unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "management-api-unavailable", "policy_error", "policy_fail_closed", "schedule_state_unavailable", "schedule_target_heartbeat_unavailable", "schedule_target_policy_unavailable", "schedule_target_status_unavailable", "schedule_target_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "management-api-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_error" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "policy_error" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_fail_closed" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "policy_fail_closed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_heartbeat_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_heartbeat_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_policy_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_policy_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_status_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_status_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "policy_error": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_error", "title": "Policy error", "status": 503, "code": "policy_error" } }, "policy_fail_closed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_fail_closed", "title": "Policy fail closed", "status": 503, "code": "policy_fail_closed" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "schedule_target_heartbeat_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_heartbeat_unavailable", "title": "Schedule target heartbeat unavailable", "status": 503, "code": "schedule_target_heartbeat_unavailable" } }, "schedule_target_policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_policy_unavailable", "title": "Schedule target policy unavailable", "status": 503, "code": "schedule_target_policy_unavailable" } }, "schedule_target_status_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_status_unavailable", "title": "Schedule target status unavailable", "status": 503, "code": "schedule_target_status_unavailable" } }, "schedule_target_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_unavailable", "title": "Schedule target unavailable", "status": 503, "code": "schedule_target_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "kind": { "type": "string", "enum": [ "assign", "onboard" ] }, "target": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "cred": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "management_type": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "model_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "os_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "peer": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "platform": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "q": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "role": { "type": "string", "pattern": "^(?:|__none|[a-z0-9][a-z0-9._-]{0,31})(?![\\s\\S])" }, "status": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "telemetry": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." } }, "required": [], "additionalProperties": false }, "device_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } }, "bind": { "type": "string", "enum": [ "late", "early" ], "default": "late" } }, "required": [], "additionalProperties": false }, "payload": { "oneOf": [ { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids" ], "additionalProperties": false }, { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "max_devices" ], "additionalProperties": false } ] }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "once" }, "at": { "type": "integer", "minimum": 0, "maximum": 253370159999 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "at", "window_seconds" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "recurring" }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Monday=0 through Sunday=6" }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "minute": { "type": "integer", "minimum": 0, "maximum": 59 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "weekday", "hour", "minute", "window_seconds" ], "additionalProperties": false } ], "description": "Server-side half-open window. A nonexistent local time resolves to the first valid instant after it; an ambiguous local time fires once at its first occurrence. Epoch fields remain integer seconds." }, "after": { "type": "object", "properties": { "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "condition": { "type": "string", "const": "min_staged_ratio" }, "min_staged_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_errored_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_missing_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "deadline_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "schedule_id", "condition", "min_staged_ratio", "max_errored_ratio", "max_missing_ratio", "deadline_seconds" ], "additionalProperties": false }, "state": { "type": "string", "enum": [ "pending", "paused", "completed" ], "default": "pending" } }, "required": [ "id", "kind", "target", "payload", "when" ], "additionalProperties": false, "allOf": [ { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "assign" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids" ], "additionalProperties": false } } } }, { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "onboard" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "max_devices" ], "additionalProperties": false } } } } ], "description": "Closed stage-only definition: assign images or onboard the staging agent. Unknown fields at every level are rejected. No install, activation, boot-variable or reload operation exists. Empty target filters and IDs select the whole fleet; explicit IDs intersect filters. Late binding resolves at fire time; early binding retains preview device IDs. A referenced target role must exist. An after gate cannot reference this schedule itself." }, "examples": { "assign": { "value": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat" } }, "onboard": { "value": { "kind": "onboard", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "telemetry": true, "telemetry_stream": false, "mode": "new-only", "max_devices": 20 }, "when": { "kind": "recurring", "weekday": 6, "hour": 2, "minute": 30, "tz": "Europe/Stockholm", "window_seconds": 3600 }, "state": "pending", "id": "s-boat" } } } } } } } }, "/api/v1/schedules/{id}": { "get": { "operationId": "console_get_api_v1_schedules_id", "summary": "Read a schedule", "description": "Read a schedule. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "example": "s-boat" } ], "responses": { "200": { "description": "Current schedule view", "headers": { "ETag": { "description": "Strong ETag of the returned schedule revision", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/ScheduleView" } }, "required": [ "schedule" ], "additionalProperties": false }, "example": { "schedule": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "etag": "\"iris-schedule-s-boat-1\"", "creator_exists": true, "next_fire": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "future", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null } } } } } }, "400": { "description": "Invalid content length or Request body not supported", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-content-length" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "request-body-not-supported" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "404": { "description": "Route not found or Schedule not found", "x-iris-problem-codes": [ "route-not-found", "schedule_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "schedule_not_found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } }, "schedule_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found", "title": "Schedule not found", "status": 404, "code": "schedule_not_found" } } } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required" }, "title": { "type": "string" }, "status": { "const": 411 }, "code": { "const": "content-length-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large" }, "title": { "type": "string" }, "status": { "const": 413 }, "code": { "const": "payload-too-large" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid schedule", "x-iris-problem-codes": [ "invalid_schedule" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Management api unavailable or Schedule state unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "management-api-unavailable", "schedule_state_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "management-api-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "put": { "operationId": "console_put_api_v1_schedules_id", "summary": "Replace a schedule", "description": "Replace a schedule. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:. Replaces the complete mutable definition, preserving id, generation, created_by and created_at.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "example": "s-boat" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "Exactly one singleton field containing the current strong schedule ETag or *. Missing: 428 precondition_required. Weak tags, comma lists, duplicate fields, malformed tags, mixed wildcard/tag values and stale tags: 412 precondition_failed. An item unknown before condition evaluation returns 404. Compare and mutation occur under the schedule shard lock; a revision race returns 412 with the newest current ETag, and a disappearance race returns 412 without an ETag. Other 412 and 428 responses include the current ETag. * matches any existing version and never creates a missing row.", "schema": { "oneOf": [ { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, { "type": "string", "const": "*" } ] }, "example": "\"iris-schedule-s-boat-1\"" } ], "responses": { "200": { "description": "Saved schedule view with server-owned identity and preview", "headers": { "ETag": { "description": "Strong ETag of the returned schedule revision", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/ScheduleView" }, "target_facts": { "type": "object", "properties": { "missing_os_family": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "role_drift": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "quarantined_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } } }, "required": [ "missing_os_family", "role_drift", "quarantined_ids" ], "additionalProperties": false } }, "required": [ "schedule", "target_facts" ], "additionalProperties": false }, "example": { "schedule": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "etag": "\"iris-schedule-s-boat-1\"", "creator_exists": true, "next_fire": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "future", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null } }, "target_facts": { "missing_os_family": 0, "role_drift": 0, "quarantined_ids": [] } } } } }, "400": { "description": "Invalid content length or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "invalid-request" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-content-length" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-request" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed" }, "title": { "type": "string" }, "status": { "const": 403 }, "code": { "const": "csrf-validation-failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found or Schedule not found", "x-iris-problem-codes": [ "route-not-found", "schedule_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "schedule_not_found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } }, "schedule_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found", "title": "Schedule not found", "status": 404, "code": "schedule_not_found" } } } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required" }, "title": { "type": "string" }, "status": { "const": 411 }, "code": { "const": "content-length-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed" }, "title": { "type": "string" }, "status": { "const": 412 }, "code": { "const": "precondition_failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large" }, "title": { "type": "string" }, "status": { "const": 413 }, "code": { "const": "payload-too-large" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid schedule or Role not found", "x-iris-problem-codes": [ "invalid_schedule", "role_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "role_not_found" }, "role": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,31}$", "not": { "enum": [ "default", "legacy", "origin", "quarantine", "seeder" ] } } }, "required": [ "type", "title", "status", "code", "role" ], "additionalProperties": false } ] }, "examples": { "invalid_schedule": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } }, "role_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found", "title": "Role not found", "status": 422, "code": "role_not_found", "role": "boat" } } } } } }, "428": { "description": "Precondition required", "x-iris-problem-codes": [ "precondition_required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required" }, "title": { "type": "string" }, "status": { "const": 428 }, "code": { "const": "precondition_required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Management api unavailable or Policy error or Policy fail closed or Schedule state unavailable or Schedule target heartbeat unavailable or Schedule target policy unavailable or Schedule target status unavailable or Schedule target unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "management-api-unavailable", "policy_error", "policy_fail_closed", "schedule_state_unavailable", "schedule_target_heartbeat_unavailable", "schedule_target_policy_unavailable", "schedule_target_status_unavailable", "schedule_target_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "management-api-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_error" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "policy_error" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_fail_closed" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "policy_fail_closed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_heartbeat_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_heartbeat_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_policy_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_policy_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_status_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_status_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "policy_error": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_error", "title": "Policy error", "status": 503, "code": "policy_error" } }, "policy_fail_closed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_fail_closed", "title": "Policy fail closed", "status": 503, "code": "policy_fail_closed" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "schedule_target_heartbeat_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_heartbeat_unavailable", "title": "Schedule target heartbeat unavailable", "status": 503, "code": "schedule_target_heartbeat_unavailable" } }, "schedule_target_policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_policy_unavailable", "title": "Schedule target policy unavailable", "status": 503, "code": "schedule_target_policy_unavailable" } }, "schedule_target_status_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_status_unavailable", "title": "Schedule target status unavailable", "status": 503, "code": "schedule_target_status_unavailable" } }, "schedule_target_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_unavailable", "title": "Schedule target unavailable", "status": 503, "code": "schedule_target_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "assign", "onboard" ] }, "target": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "cred": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "management_type": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "model_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "os_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "peer": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "platform": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "q": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "role": { "type": "string", "pattern": "^(?:|__none|[a-z0-9][a-z0-9._-]{0,31})(?![\\s\\S])" }, "status": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "telemetry": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." } }, "required": [], "additionalProperties": false }, "device_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } }, "bind": { "type": "string", "enum": [ "late", "early" ], "default": "late" } }, "required": [], "additionalProperties": false }, "payload": { "oneOf": [ { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids" ], "additionalProperties": false }, { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "max_devices" ], "additionalProperties": false } ] }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "once" }, "at": { "type": "integer", "minimum": 0, "maximum": 253370159999 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "at", "window_seconds" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "recurring" }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Monday=0 through Sunday=6" }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "minute": { "type": "integer", "minimum": 0, "maximum": 59 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "weekday", "hour", "minute", "window_seconds" ], "additionalProperties": false } ], "description": "Server-side half-open window. A nonexistent local time resolves to the first valid instant after it; an ambiguous local time fires once at its first occurrence. Epoch fields remain integer seconds." }, "after": { "type": "object", "properties": { "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "condition": { "type": "string", "const": "min_staged_ratio" }, "min_staged_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_errored_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_missing_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "deadline_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "schedule_id", "condition", "min_staged_ratio", "max_errored_ratio", "max_missing_ratio", "deadline_seconds" ], "additionalProperties": false }, "state": { "type": "string", "enum": [ "pending", "paused", "completed" ], "default": "pending" } }, "required": [ "kind", "target", "payload", "when" ], "additionalProperties": false, "allOf": [ { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "assign" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids" ], "additionalProperties": false } } } }, { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "onboard" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "max_devices" ], "additionalProperties": false } } } } ], "description": "Closed stage-only definition: assign images or onboard the staging agent. Unknown fields at every level are rejected. No install, activation, boot-variable or reload operation exists. Empty target filters and IDs select the whole fleet; explicit IDs intersect filters. Late binding resolves at fire time; early binding retains preview device IDs. A referenced target role must exist. An after gate cannot reference this schedule itself." }, "examples": { "assign": { "value": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending" } }, "onboard": { "value": { "kind": "onboard", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "telemetry": true, "telemetry_stream": false, "mode": "new-only", "max_devices": 20 }, "when": { "kind": "recurring", "weekday": 6, "hour": 2, "minute": 30, "tz": "Europe/Stockholm", "window_seconds": 3600 }, "state": "pending" } } } } } } }, "patch": { "operationId": "console_patch_api_v1_schedules_id", "summary": "Update a schedule", "description": "Update a schedule. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:. Replaces supplied top-level subobjects in full; after:null removes the gate. target_facts is null unless the target is replaced.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "example": "s-boat" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "Exactly one singleton field containing the current strong schedule ETag or *. Missing: 428 precondition_required. Weak tags, comma lists, duplicate fields, malformed tags, mixed wildcard/tag values and stale tags: 412 precondition_failed. An item unknown before condition evaluation returns 404. Compare and mutation occur under the schedule shard lock; a revision race returns 412 with the newest current ETag, and a disappearance race returns 412 without an ETag. Other 412 and 428 responses include the current ETag. * matches any existing version and never creates a missing row.", "schema": { "oneOf": [ { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, { "type": "string", "const": "*" } ] }, "example": "\"iris-schedule-s-boat-1\"" } ], "responses": { "200": { "description": "Saved schedule view with server-owned identity and preview; target_facts is null when the patch does not retarget", "headers": { "ETag": { "description": "Strong ETag of the returned schedule revision", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/ScheduleView" }, "target_facts": { "oneOf": [ { "type": "object", "properties": { "missing_os_family": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "role_drift": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "quarantined_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } } }, "required": [ "missing_os_family", "role_drift", "quarantined_ids" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "schedule", "target_facts" ], "additionalProperties": false }, "examples": { "retarget": { "value": { "schedule": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "etag": "\"iris-schedule-s-boat-1\"", "creator_exists": true, "next_fire": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "future", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null } }, "target_facts": { "missing_os_family": 0, "role_drift": 0, "quarantined_ids": [] } } }, "definitionOnly": { "value": { "schedule": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "etag": "\"iris-schedule-s-boat-1\"", "creator_exists": true, "next_fire": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "future", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null } }, "target_facts": null } } } } } }, "400": { "description": "Invalid content length or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "invalid-request" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-content-length" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-request" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed" }, "title": { "type": "string" }, "status": { "const": 403 }, "code": { "const": "csrf-validation-failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found or Schedule not found", "x-iris-problem-codes": [ "route-not-found", "schedule_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "schedule_not_found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } }, "schedule_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found", "title": "Schedule not found", "status": 404, "code": "schedule_not_found" } } } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required" }, "title": { "type": "string" }, "status": { "const": 411 }, "code": { "const": "content-length-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed" }, "title": { "type": "string" }, "status": { "const": 412 }, "code": { "const": "precondition_failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large" }, "title": { "type": "string" }, "status": { "const": 413 }, "code": { "const": "payload-too-large" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid schedule or Role not found", "x-iris-problem-codes": [ "invalid_schedule", "role_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "role_not_found" }, "role": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,31}$", "not": { "enum": [ "default", "legacy", "origin", "quarantine", "seeder" ] } } }, "required": [ "type", "title", "status", "code", "role" ], "additionalProperties": false } ] }, "examples": { "invalid_schedule": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } }, "role_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found", "title": "Role not found", "status": 422, "code": "role_not_found", "role": "boat" } } } } } }, "428": { "description": "Precondition required", "x-iris-problem-codes": [ "precondition_required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required" }, "title": { "type": "string" }, "status": { "const": 428 }, "code": { "const": "precondition_required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Management api unavailable or Policy error or Policy fail closed or Schedule state unavailable or Schedule target heartbeat unavailable or Schedule target policy unavailable or Schedule target status unavailable or Schedule target unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "management-api-unavailable", "policy_error", "policy_fail_closed", "schedule_state_unavailable", "schedule_target_heartbeat_unavailable", "schedule_target_policy_unavailable", "schedule_target_status_unavailable", "schedule_target_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "management-api-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_error" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "policy_error" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_fail_closed" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "policy_fail_closed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_heartbeat_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_heartbeat_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_policy_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_policy_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_status_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_status_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "policy_error": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_error", "title": "Policy error", "status": 503, "code": "policy_error" } }, "policy_fail_closed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_fail_closed", "title": "Policy fail closed", "status": 503, "code": "policy_fail_closed" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "schedule_target_heartbeat_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_heartbeat_unavailable", "title": "Schedule target heartbeat unavailable", "status": 503, "code": "schedule_target_heartbeat_unavailable" } }, "schedule_target_policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_policy_unavailable", "title": "Schedule target policy unavailable", "status": 503, "code": "schedule_target_policy_unavailable" } }, "schedule_target_status_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_status_unavailable", "title": "Schedule target status unavailable", "status": 503, "code": "schedule_target_status_unavailable" } }, "schedule_target_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_unavailable", "title": "Schedule target unavailable", "status": 503, "code": "schedule_target_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "assign", "onboard" ] }, "target": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "cred": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "management_type": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "model_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "os_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "peer": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "platform": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "q": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "role": { "type": "string", "pattern": "^(?:|__none|[a-z0-9][a-z0-9._-]{0,31})(?![\\s\\S])" }, "status": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "telemetry": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." } }, "required": [], "additionalProperties": false }, "device_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } }, "bind": { "type": "string", "enum": [ "late", "early" ], "default": "late" } }, "required": [], "additionalProperties": false }, "payload": { "oneOf": [ { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids" ], "additionalProperties": false }, { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "max_devices" ], "additionalProperties": false } ] }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "once" }, "at": { "type": "integer", "minimum": 0, "maximum": 253370159999 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "at", "window_seconds" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "recurring" }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Monday=0 through Sunday=6" }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "minute": { "type": "integer", "minimum": 0, "maximum": 59 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "weekday", "hour", "minute", "window_seconds" ], "additionalProperties": false } ], "description": "Server-side half-open window. A nonexistent local time resolves to the first valid instant after it; an ambiguous local time fires once at its first occurrence. Epoch fields remain integer seconds." }, "after": { "oneOf": [ { "type": "object", "properties": { "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "condition": { "type": "string", "const": "min_staged_ratio" }, "min_staged_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_errored_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_missing_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "deadline_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "schedule_id", "condition", "min_staged_ratio", "max_errored_ratio", "max_missing_ratio", "deadline_seconds" ], "additionalProperties": false }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "pending", "paused", "completed" ], "default": "pending" } }, "required": [], "additionalProperties": false, "allOf": [ { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "assign" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids" ], "additionalProperties": false } } } }, { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "onboard" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "max_devices" ], "additionalProperties": false } } } } ], "description": "Closed stage-only definition: assign images or onboard the staging agent. Unknown fields at every level are rejected. No install, activation, boot-variable or reload operation exists. Empty target filters and IDs select the whole fleet; explicit IDs intersect filters. Late binding resolves at fire time; early binding retains preview device IDs. A referenced target role must exist. An after gate cannot reference this schedule itself. PATCH replaces supplied top-level subobjects in full, without recursive merge; after:null removes the gate. The resulting complete definition is validated, including compatibility between an omitted existing kind and a supplied payload." }, "examples": { "pause": { "value": { "state": "paused" } }, "removeGate": { "value": { "after": null } }, "retarget": { "value": { "target": { "filters": { "role": "boat" }, "bind": "late" } } } } } } } }, "delete": { "operationId": "console_delete_api_v1_schedules_id", "summary": "Delete a schedule", "description": "Delete a schedule. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:. Deletion remains allowed when a referenced role or creator is gone.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "example": "s-boat" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "Exactly one singleton field containing the current strong schedule ETag or *. Missing: 428 precondition_required. Weak tags, comma lists, duplicate fields, malformed tags, mixed wildcard/tag values and stale tags: 412 precondition_failed. An item unknown before condition evaluation returns 404. Compare and mutation occur under the schedule shard lock; a revision race returns 412 with the newest current ETag, and a disappearance race returns 412 without an ETag. Other 412 and 428 responses include the current ETag. * matches any existing version and never creates a missing row.", "schema": { "oneOf": [ { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, { "type": "string", "const": "*" } ] }, "example": "\"iris-schedule-s-boat-1\"" } ], "responses": { "204": { "description": "Schedule deleted; empty body", "headers": { "ETag": { "description": "Successfully matched predecessor ETag, including wildcard deletion", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "400": { "description": "Invalid content length or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "invalid-request" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-content-length" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-request" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed" }, "title": { "type": "string" }, "status": { "const": 403 }, "code": { "const": "csrf-validation-failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found or Schedule not found", "x-iris-problem-codes": [ "route-not-found", "schedule_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "schedule_not_found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } }, "schedule_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found", "title": "Schedule not found", "status": 404, "code": "schedule_not_found" } } } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required" }, "title": { "type": "string" }, "status": { "const": 411 }, "code": { "const": "content-length-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed" }, "title": { "type": "string" }, "status": { "const": 412 }, "code": { "const": "precondition_failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large" }, "title": { "type": "string" }, "status": { "const": 413 }, "code": { "const": "payload-too-large" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid schedule", "x-iris-problem-codes": [ "invalid_schedule" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } } } }, "428": { "description": "Precondition required", "x-iris-problem-codes": [ "precondition_required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required" }, "title": { "type": "string" }, "status": { "const": 428 }, "code": { "const": "precondition_required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Management api unavailable or Schedule state unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "management-api-unavailable", "schedule_state_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "management-api-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/schedules/{id}/occurrences": { "get": { "operationId": "console_get_api_v1_schedules_id_occurrences", "summary": "List schedule occurrences", "description": "List schedule occurrences. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "example": "s-boat" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum occurrences across this schedule", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "example": 100 }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset in scheduled_at and occurrence-id order", "schema": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807, "default": 0 }, "example": 0 } ], "responses": { "200": { "description": "Schedule-wide occurrence page, ordered by scheduled_at and occurrence id. It retains missed and empty-target outcomes even when they have no per-device receipts or the definition was deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "occurrences": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/ScheduleOccurrence" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "truncated": { "type": "boolean" } }, "required": [ "schedule_id", "occurrences", "total", "offset", "truncated" ], "additionalProperties": false }, "example": { "schedule_id": "s-boat", "occurrences": [ { "id": "6f9753e0d633aab2c497b14f23d9bc21", "schedule_id": "s-boat", "schedule_generation": "00000000000000000000000000000000", "schedule_rev": 1, "schedule": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] } }, "actor": "schedule:s-boat", "slot": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "due", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null }, "scheduled_at": 1788883260, "window_end": 1788886860, "state": "completed", "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "target_snapshot": { "revision": 3, "now": 1788883260, "device_ids": [ "edge-01" ] }, "delta": { "added": 0, "removed": 0 }, "created_at": 1788883260, "updated_at": 1788883300 } ], "total": 1, "offset": 0, "truncated": false } } } }, "400": { "description": "Invalid content length or Request body not supported", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-content-length" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "request-body-not-supported" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "404": { "description": "Route not found or Schedule not found", "x-iris-problem-codes": [ "route-not-found", "schedule_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "schedule_not_found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } }, "schedule_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found", "title": "Schedule not found", "status": 404, "code": "schedule_not_found" } } } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required" }, "title": { "type": "string" }, "status": { "const": 411 }, "code": { "const": "content-length-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large" }, "title": { "type": "string" }, "status": { "const": 413 }, "code": { "const": "payload-too-large" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid schedule", "x-iris-problem-codes": [ "invalid_schedule" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Management api unavailable or Schedule state unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "management-api-unavailable", "schedule_state_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "management-api-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/schedules/{id}/receipts": { "get": { "operationId": "console_get_api_v1_schedules_id_receipts", "summary": "List schedule receipts", "description": "List schedule receipts. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "example": "s-boat" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum receipts across this schedule", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 }, "example": 100 }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset in scheduled_at, occurrence_id, device_id order", "schema": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807, "default": 0 }, "example": 0 } ], "responses": { "200": { "description": "Schedule-wide receipt page, ordered by scheduled_at, occurrence_id, device_id. total counts all receipts; truncated is true when offset is nonzero or more rows remain. The response cap never prunes durable evidence.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "receipts": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/ScheduleReceipt" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "truncated": { "type": "boolean" } }, "required": [ "schedule_id", "receipts", "total", "offset", "truncated" ], "additionalProperties": false }, "example": { "schedule_id": "s-boat", "receipts": [ { "occurrence_id": "11111111111111111111111111111111", "device_id": "edge-01", "rev": 1, "attempt": 1, "attempt_started_at": 1788883260, "predecessors": [], "status": "ok", "reason": "assigned", "created_at": 1788883260, "updated_at": 1788883260, "completed_at": 1788883260, "notes": [], "schedule_id": "s-boat", "scheduled_at": 1788883260, "window_end": 1788886860, "occurrence_state": "completed", "schedule_rev": 1, "before_image_ids": [], "after_image_ids": [ "image-a" ], "removed_image_ids": [] } ], "total": 1, "offset": 0, "truncated": false } } } }, "400": { "description": "Invalid content length or Request body not supported", "x-iris-problem-codes": [ "invalid-content-length", "request-body-not-supported" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-content-length" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "request-body-not-supported" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "request-body-not-supported": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#request-body-not-supported", "title": "Request body not supported", "status": 400, "code": "request-body-not-supported" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "404": { "description": "Route not found or Schedule not found", "x-iris-problem-codes": [ "route-not-found", "schedule_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "schedule_not_found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } }, "schedule_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found", "title": "Schedule not found", "status": 404, "code": "schedule_not_found" } } } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required" }, "title": { "type": "string" }, "status": { "const": 411 }, "code": { "const": "content-length-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large" }, "title": { "type": "string" }, "status": { "const": 413 }, "code": { "const": "payload-too-large" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid schedule", "x-iris-problem-codes": [ "invalid_schedule" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Management api unavailable or Schedule state unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "management-api-unavailable", "schedule_state_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "management-api-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/schedules/{id}/reaffirm": { "post": { "operationId": "console_post_api_v1_schedules_id_reaffirm", "summary": "Reaffirm a schedule", "description": "Reaffirm a schedule. Browser-facing BFF route; session/CSRF decisions are repeated by the state owner before request-body forwarding. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:. Accepts an empty object only. Replaces created_by with console: derived server-side; identity fields cannot be supplied by the caller.", "tags": [ "console" ], "x-iris-service": "console", "x-iris-security": "consoleSession", "servers": [ { "url": "https://iris.example:8080", "description": "Operator Console; replace with the configured public origin" } ], "security": [ { "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "example": "s-boat" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "Exactly one singleton field containing the current strong schedule ETag or *. Missing: 428 precondition_required. Weak tags, comma lists, duplicate fields, malformed tags, mixed wildcard/tag values and stale tags: 412 precondition_failed. An item unknown before condition evaluation returns 404. Compare and mutation occur under the schedule shard lock; a revision race returns 412 with the newest current ETag, and a disappearance race returns 412 without an ETag. Other 412 and 428 responses include the current ETag. * matches any existing version and never creates a missing row.", "schema": { "oneOf": [ { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, { "type": "string", "const": "*" } ] }, "example": "\"iris-schedule-s-boat-1\"" } ], "responses": { "200": { "description": "Saved schedule view with server-owned identity and preview", "headers": { "ETag": { "description": "Strong ETag of the returned schedule revision", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/ScheduleView" } }, "required": [ "schedule" ], "additionalProperties": false }, "example": { "schedule": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "etag": "\"iris-schedule-s-boat-1\"", "creator_exists": true, "next_fire": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "future", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null } } } } } }, "400": { "description": "Invalid content length or Invalid request", "x-iris-problem-codes": [ "invalid-content-length", "invalid-request" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-content-length" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-request" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "invalid-content-length": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-content-length", "title": "Invalid content length", "status": 400, "code": "invalid-content-length" } }, "invalid-request": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed" }, "title": { "type": "string" }, "status": { "const": 403 }, "code": { "const": "csrf-validation-failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found or Schedule not found", "x-iris-problem-codes": [ "route-not-found", "schedule_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "schedule_not_found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } }, "schedule_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found", "title": "Schedule not found", "status": 404, "code": "schedule_not_found" } } } } } }, "411": { "description": "Content length required", "x-iris-problem-codes": [ "content-length-required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required" }, "title": { "type": "string" }, "status": { "const": 411 }, "code": { "const": "content-length-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#content-length-required", "title": "Content length required", "status": 411, "code": "content-length-required" } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed" }, "title": { "type": "string" }, "status": { "const": 412 }, "code": { "const": "precondition_failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large" }, "title": { "type": "string" }, "status": { "const": 413 }, "code": { "const": "payload-too-large" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid schedule", "x-iris-problem-codes": [ "invalid_schedule" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } } } }, "428": { "description": "Precondition required", "x-iris-problem-codes": [ "precondition_required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required" }, "title": { "type": "string" }, "status": { "const": 428 }, "code": { "const": "precondition_required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Management api unavailable or Schedule state unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "management-api-unavailable", "schedule_state_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "management-api-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "management-api-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-api-unavailable", "title": "Management api unavailable", "status": 503, "code": "management-api-unavailable" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } } } }, "/internal/v1/schedules": { "get": { "operationId": "management_get_internal_v1_schedules", "summary": "List schedules", "description": "List schedules. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "All schedules; each row includes its own ETag, with no collection ETag", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedules": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleView" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } }, "required": [ "schedules", "total" ], "additionalProperties": false }, "example": { "schedules": [ { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "etag": "\"iris-schedule-s-boat-1\"", "creator_exists": true, "next_fire": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "future", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null } } ], "total": 1 } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "422": { "description": "Invalid schedule", "x-iris-problem-codes": [ "invalid_schedule" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Schedule state unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "schedule_state_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "post": { "operationId": "management_post_internal_v1_schedules", "summary": "Create a schedule", "description": "Create a schedule. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:. Create-if-absent: the caller selects id; a duplicate returns 409 schedule_conflict. The server supplies generation, revision, creator, creation time and target preview. No If-Match or process-local Idempotency-Key replay is required; inspect the selected id after an uncertain retry.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" } ], "responses": { "201": { "description": "Saved schedule view with server-owned identity and preview", "headers": { "ETag": { "description": "Strong ETag of the returned schedule revision", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" }, "Location": { "description": "Versioned resource path of the created schedule", "schema": { "type": "string", "format": "uri-reference" }, "example": "/internal/v1/schedules/s-boat" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/ScheduleView" }, "target_facts": { "type": "object", "properties": { "missing_os_family": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "role_drift": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "quarantined_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } } }, "required": [ "missing_os_family", "role_drift", "quarantined_ids" ], "additionalProperties": false } }, "required": [ "schedule", "target_facts" ], "additionalProperties": false }, "example": { "schedule": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "etag": "\"iris-schedule-s-boat-1\"", "creator_exists": true, "next_fire": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "future", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null } }, "target_facts": { "missing_os_family": 0, "role_drift": 0, "quarantined_ids": [] } } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-request" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed" }, "title": { "type": "string" }, "status": { "const": 403 }, "code": { "const": "csrf-validation-failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found", "x-iris-problem-codes": [ "route-not-found" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } } } }, "409": { "description": "Schedule conflict", "x-iris-problem-codes": [ "schedule_conflict" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_conflict" }, "title": { "type": "string" }, "status": { "const": 409 }, "code": { "const": "schedule_conflict" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_conflict", "title": "Schedule conflict", "status": 409, "code": "schedule_conflict" } } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large" }, "title": { "type": "string" }, "status": { "const": 413 }, "code": { "const": "payload-too-large" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid schedule or Role not found", "x-iris-problem-codes": [ "invalid_schedule", "role_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "role_not_found" }, "role": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,31}$", "not": { "enum": [ "default", "legacy", "origin", "quarantine", "seeder" ] } } }, "required": [ "type", "title", "status", "code", "role" ], "additionalProperties": false } ] }, "examples": { "invalid_schedule": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } }, "role_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found", "title": "Role not found", "status": 422, "code": "role_not_found", "role": "boat" } } } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Policy error or Policy fail closed or Schedule state unavailable or Schedule target heartbeat unavailable or Schedule target policy unavailable or Schedule target status unavailable or Schedule target unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "policy_error", "policy_fail_closed", "schedule_state_unavailable", "schedule_target_heartbeat_unavailable", "schedule_target_policy_unavailable", "schedule_target_status_unavailable", "schedule_target_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_error" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "policy_error" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_fail_closed" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "policy_fail_closed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_heartbeat_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_heartbeat_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_policy_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_policy_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_status_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_status_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "policy_error": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_error", "title": "Policy error", "status": 503, "code": "policy_error" } }, "policy_fail_closed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_fail_closed", "title": "Policy fail closed", "status": 503, "code": "policy_fail_closed" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "schedule_target_heartbeat_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_heartbeat_unavailable", "title": "Schedule target heartbeat unavailable", "status": 503, "code": "schedule_target_heartbeat_unavailable" } }, "schedule_target_policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_policy_unavailable", "title": "Schedule target policy unavailable", "status": 503, "code": "schedule_target_policy_unavailable" } }, "schedule_target_status_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_status_unavailable", "title": "Schedule target status unavailable", "status": 503, "code": "schedule_target_status_unavailable" } }, "schedule_target_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_unavailable", "title": "Schedule target unavailable", "status": 503, "code": "schedule_target_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "kind": { "type": "string", "enum": [ "assign", "onboard" ] }, "target": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "cred": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "management_type": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "model_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "os_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "peer": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "platform": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "q": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "role": { "type": "string", "pattern": "^(?:|__none|[a-z0-9][a-z0-9._-]{0,31})(?![\\s\\S])" }, "status": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "telemetry": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." } }, "required": [], "additionalProperties": false }, "device_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } }, "bind": { "type": "string", "enum": [ "late", "early" ], "default": "late" } }, "required": [], "additionalProperties": false }, "payload": { "oneOf": [ { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids" ], "additionalProperties": false }, { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "max_devices" ], "additionalProperties": false } ] }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "once" }, "at": { "type": "integer", "minimum": 0, "maximum": 253370159999 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "at", "window_seconds" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "recurring" }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Monday=0 through Sunday=6" }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "minute": { "type": "integer", "minimum": 0, "maximum": 59 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "weekday", "hour", "minute", "window_seconds" ], "additionalProperties": false } ], "description": "Server-side half-open window. A nonexistent local time resolves to the first valid instant after it; an ambiguous local time fires once at its first occurrence. Epoch fields remain integer seconds." }, "after": { "type": "object", "properties": { "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "condition": { "type": "string", "const": "min_staged_ratio" }, "min_staged_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_errored_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_missing_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "deadline_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "schedule_id", "condition", "min_staged_ratio", "max_errored_ratio", "max_missing_ratio", "deadline_seconds" ], "additionalProperties": false }, "state": { "type": "string", "enum": [ "pending", "paused", "completed" ], "default": "pending" } }, "required": [ "id", "kind", "target", "payload", "when" ], "additionalProperties": false, "allOf": [ { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "assign" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids" ], "additionalProperties": false } } } }, { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "onboard" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "max_devices" ], "additionalProperties": false } } } } ], "description": "Closed stage-only definition: assign images or onboard the staging agent. Unknown fields at every level are rejected. No install, activation, boot-variable or reload operation exists. Empty target filters and IDs select the whole fleet; explicit IDs intersect filters. Late binding resolves at fire time; early binding retains preview device IDs. A referenced target role must exist. An after gate cannot reference this schedule itself." }, "examples": { "assign": { "value": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat" } }, "onboard": { "value": { "kind": "onboard", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "telemetry": true, "telemetry_stream": false, "mode": "new-only", "max_devices": 20 }, "when": { "kind": "recurring", "weekday": 6, "hour": 2, "minute": 30, "tz": "Europe/Stockholm", "window_seconds": 3600 }, "state": "pending", "id": "s-boat" } } } } } } } }, "/internal/v1/schedules/{id}": { "get": { "operationId": "management_get_internal_v1_schedules_id", "summary": "Read a schedule", "description": "Read a schedule. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "example": "s-boat" } ], "responses": { "200": { "description": "Current schedule view", "headers": { "ETag": { "description": "Strong ETag of the returned schedule revision", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/ScheduleView" } }, "required": [ "schedule" ], "additionalProperties": false }, "example": { "schedule": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "etag": "\"iris-schedule-s-boat-1\"", "creator_exists": true, "next_fire": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "future", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null } } } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Route not found or Schedule not found", "x-iris-problem-codes": [ "route-not-found", "schedule_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "schedule_not_found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } }, "schedule_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found", "title": "Schedule not found", "status": 404, "code": "schedule_not_found" } } } } } }, "422": { "description": "Invalid schedule", "x-iris-problem-codes": [ "invalid_schedule" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Schedule state unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "schedule_state_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } }, "put": { "operationId": "management_put_internal_v1_schedules_id", "summary": "Replace a schedule", "description": "Replace a schedule. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:. Replaces the complete mutable definition, preserving id, generation, created_by and created_at.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "example": "s-boat" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "Exactly one singleton field containing the current strong schedule ETag or *. Missing: 428 precondition_required. Weak tags, comma lists, duplicate fields, malformed tags, mixed wildcard/tag values and stale tags: 412 precondition_failed. An item unknown before condition evaluation returns 404. Compare and mutation occur under the schedule shard lock; a revision race returns 412 with the newest current ETag, and a disappearance race returns 412 without an ETag. Other 412 and 428 responses include the current ETag. * matches any existing version and never creates a missing row.", "schema": { "oneOf": [ { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, { "type": "string", "const": "*" } ] }, "example": "\"iris-schedule-s-boat-1\"" } ], "responses": { "200": { "description": "Saved schedule view with server-owned identity and preview", "headers": { "ETag": { "description": "Strong ETag of the returned schedule revision", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/ScheduleView" }, "target_facts": { "type": "object", "properties": { "missing_os_family": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "role_drift": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "quarantined_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } } }, "required": [ "missing_os_family", "role_drift", "quarantined_ids" ], "additionalProperties": false } }, "required": [ "schedule", "target_facts" ], "additionalProperties": false }, "example": { "schedule": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "etag": "\"iris-schedule-s-boat-1\"", "creator_exists": true, "next_fire": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "future", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null } }, "target_facts": { "missing_os_family": 0, "role_drift": 0, "quarantined_ids": [] } } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-request" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed" }, "title": { "type": "string" }, "status": { "const": 403 }, "code": { "const": "csrf-validation-failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found or Schedule not found", "x-iris-problem-codes": [ "route-not-found", "schedule_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "schedule_not_found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } }, "schedule_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found", "title": "Schedule not found", "status": 404, "code": "schedule_not_found" } } } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed" }, "title": { "type": "string" }, "status": { "const": 412 }, "code": { "const": "precondition_failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large" }, "title": { "type": "string" }, "status": { "const": 413 }, "code": { "const": "payload-too-large" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid schedule or Role not found", "x-iris-problem-codes": [ "invalid_schedule", "role_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "role_not_found" }, "role": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,31}$", "not": { "enum": [ "default", "legacy", "origin", "quarantine", "seeder" ] } } }, "required": [ "type", "title", "status", "code", "role" ], "additionalProperties": false } ] }, "examples": { "invalid_schedule": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } }, "role_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found", "title": "Role not found", "status": 422, "code": "role_not_found", "role": "boat" } } } } } }, "428": { "description": "Precondition required", "x-iris-problem-codes": [ "precondition_required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required" }, "title": { "type": "string" }, "status": { "const": 428 }, "code": { "const": "precondition_required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Policy error or Policy fail closed or Schedule state unavailable or Schedule target heartbeat unavailable or Schedule target policy unavailable or Schedule target status unavailable or Schedule target unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "policy_error", "policy_fail_closed", "schedule_state_unavailable", "schedule_target_heartbeat_unavailable", "schedule_target_policy_unavailable", "schedule_target_status_unavailable", "schedule_target_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_error" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "policy_error" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_fail_closed" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "policy_fail_closed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_heartbeat_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_heartbeat_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_policy_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_policy_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_status_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_status_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "policy_error": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_error", "title": "Policy error", "status": 503, "code": "policy_error" } }, "policy_fail_closed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_fail_closed", "title": "Policy fail closed", "status": 503, "code": "policy_fail_closed" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "schedule_target_heartbeat_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_heartbeat_unavailable", "title": "Schedule target heartbeat unavailable", "status": 503, "code": "schedule_target_heartbeat_unavailable" } }, "schedule_target_policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_policy_unavailable", "title": "Schedule target policy unavailable", "status": 503, "code": "schedule_target_policy_unavailable" } }, "schedule_target_status_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_status_unavailable", "title": "Schedule target status unavailable", "status": 503, "code": "schedule_target_status_unavailable" } }, "schedule_target_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_unavailable", "title": "Schedule target unavailable", "status": 503, "code": "schedule_target_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "assign", "onboard" ] }, "target": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "cred": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "management_type": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "model_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "os_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "peer": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "platform": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "q": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "role": { "type": "string", "pattern": "^(?:|__none|[a-z0-9][a-z0-9._-]{0,31})(?![\\s\\S])" }, "status": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "telemetry": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." } }, "required": [], "additionalProperties": false }, "device_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } }, "bind": { "type": "string", "enum": [ "late", "early" ], "default": "late" } }, "required": [], "additionalProperties": false }, "payload": { "oneOf": [ { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids" ], "additionalProperties": false }, { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "max_devices" ], "additionalProperties": false } ] }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "once" }, "at": { "type": "integer", "minimum": 0, "maximum": 253370159999 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "at", "window_seconds" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "recurring" }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Monday=0 through Sunday=6" }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "minute": { "type": "integer", "minimum": 0, "maximum": 59 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "weekday", "hour", "minute", "window_seconds" ], "additionalProperties": false } ], "description": "Server-side half-open window. A nonexistent local time resolves to the first valid instant after it; an ambiguous local time fires once at its first occurrence. Epoch fields remain integer seconds." }, "after": { "type": "object", "properties": { "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "condition": { "type": "string", "const": "min_staged_ratio" }, "min_staged_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_errored_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_missing_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "deadline_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "schedule_id", "condition", "min_staged_ratio", "max_errored_ratio", "max_missing_ratio", "deadline_seconds" ], "additionalProperties": false }, "state": { "type": "string", "enum": [ "pending", "paused", "completed" ], "default": "pending" } }, "required": [ "kind", "target", "payload", "when" ], "additionalProperties": false, "allOf": [ { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "assign" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids" ], "additionalProperties": false } } } }, { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "onboard" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "max_devices" ], "additionalProperties": false } } } } ], "description": "Closed stage-only definition: assign images or onboard the staging agent. Unknown fields at every level are rejected. No install, activation, boot-variable or reload operation exists. Empty target filters and IDs select the whole fleet; explicit IDs intersect filters. Late binding resolves at fire time; early binding retains preview device IDs. A referenced target role must exist. An after gate cannot reference this schedule itself." }, "examples": { "assign": { "value": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending" } }, "onboard": { "value": { "kind": "onboard", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "telemetry": true, "telemetry_stream": false, "mode": "new-only", "max_devices": 20 }, "when": { "kind": "recurring", "weekday": 6, "hour": 2, "minute": 30, "tz": "Europe/Stockholm", "window_seconds": 3600 }, "state": "pending" } } } } } } }, "patch": { "operationId": "management_patch_internal_v1_schedules_id", "summary": "Update a schedule", "description": "Update a schedule. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:. Replaces supplied top-level subobjects in full; after:null removes the gate. target_facts is null unless the target is replaced.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "example": "s-boat" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "Exactly one singleton field containing the current strong schedule ETag or *. Missing: 428 precondition_required. Weak tags, comma lists, duplicate fields, malformed tags, mixed wildcard/tag values and stale tags: 412 precondition_failed. An item unknown before condition evaluation returns 404. Compare and mutation occur under the schedule shard lock; a revision race returns 412 with the newest current ETag, and a disappearance race returns 412 without an ETag. Other 412 and 428 responses include the current ETag. * matches any existing version and never creates a missing row.", "schema": { "oneOf": [ { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, { "type": "string", "const": "*" } ] }, "example": "\"iris-schedule-s-boat-1\"" } ], "responses": { "200": { "description": "Saved schedule view with server-owned identity and preview; target_facts is null when the patch does not retarget", "headers": { "ETag": { "description": "Strong ETag of the returned schedule revision", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/ScheduleView" }, "target_facts": { "oneOf": [ { "type": "object", "properties": { "missing_os_family": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "role_drift": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "quarantined_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } } }, "required": [ "missing_os_family", "role_drift", "quarantined_ids" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "schedule", "target_facts" ], "additionalProperties": false }, "examples": { "retarget": { "value": { "schedule": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "etag": "\"iris-schedule-s-boat-1\"", "creator_exists": true, "next_fire": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "future", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null } }, "target_facts": { "missing_os_family": 0, "role_drift": 0, "quarantined_ids": [] } } }, "definitionOnly": { "value": { "schedule": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "etag": "\"iris-schedule-s-boat-1\"", "creator_exists": true, "next_fire": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "future", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null } }, "target_facts": null } } } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-request" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed" }, "title": { "type": "string" }, "status": { "const": 403 }, "code": { "const": "csrf-validation-failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found or Schedule not found", "x-iris-problem-codes": [ "route-not-found", "schedule_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "schedule_not_found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } }, "schedule_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found", "title": "Schedule not found", "status": 404, "code": "schedule_not_found" } } } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed" }, "title": { "type": "string" }, "status": { "const": 412 }, "code": { "const": "precondition_failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large" }, "title": { "type": "string" }, "status": { "const": 413 }, "code": { "const": "payload-too-large" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid schedule or Role not found", "x-iris-problem-codes": [ "invalid_schedule", "role_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "role_not_found" }, "role": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,31}$", "not": { "enum": [ "default", "legacy", "origin", "quarantine", "seeder" ] } } }, "required": [ "type", "title", "status", "code", "role" ], "additionalProperties": false } ] }, "examples": { "invalid_schedule": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } }, "role_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#role_not_found", "title": "Role not found", "status": 422, "code": "role_not_found", "role": "boat" } } } } } }, "428": { "description": "Precondition required", "x-iris-problem-codes": [ "precondition_required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required" }, "title": { "type": "string" }, "status": { "const": 428 }, "code": { "const": "precondition_required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Policy error or Policy fail closed or Schedule state unavailable or Schedule target heartbeat unavailable or Schedule target policy unavailable or Schedule target status unavailable or Schedule target unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "policy_error", "policy_fail_closed", "schedule_state_unavailable", "schedule_target_heartbeat_unavailable", "schedule_target_policy_unavailable", "schedule_target_status_unavailable", "schedule_target_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_error" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "policy_error" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_fail_closed" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "policy_fail_closed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_heartbeat_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_heartbeat_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_policy_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_policy_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_status_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_status_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_target_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "policy_error": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_error", "title": "Policy error", "status": 503, "code": "policy_error" } }, "policy_fail_closed": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#policy_fail_closed", "title": "Policy fail closed", "status": 503, "code": "policy_fail_closed" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "schedule_target_heartbeat_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_heartbeat_unavailable", "title": "Schedule target heartbeat unavailable", "status": 503, "code": "schedule_target_heartbeat_unavailable" } }, "schedule_target_policy_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_policy_unavailable", "title": "Schedule target policy unavailable", "status": 503, "code": "schedule_target_policy_unavailable" } }, "schedule_target_status_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_status_unavailable", "title": "Schedule target status unavailable", "status": 503, "code": "schedule_target_status_unavailable" } }, "schedule_target_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_target_unavailable", "title": "Schedule target unavailable", "status": 503, "code": "schedule_target_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "assign", "onboard" ] }, "target": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "cred": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "management_type": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "model_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "os_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "peer": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "platform": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "q": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "role": { "type": "string", "pattern": "^(?:|__none|[a-z0-9][a-z0-9._-]{0,31})(?![\\s\\S])" }, "status": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "telemetry": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." } }, "required": [], "additionalProperties": false }, "device_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } }, "bind": { "type": "string", "enum": [ "late", "early" ], "default": "late" } }, "required": [], "additionalProperties": false }, "payload": { "oneOf": [ { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids" ], "additionalProperties": false }, { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "max_devices" ], "additionalProperties": false } ] }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "once" }, "at": { "type": "integer", "minimum": 0, "maximum": 253370159999 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "at", "window_seconds" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "recurring" }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Monday=0 through Sunday=6" }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "minute": { "type": "integer", "minimum": 0, "maximum": 59 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "weekday", "hour", "minute", "window_seconds" ], "additionalProperties": false } ], "description": "Server-side half-open window. A nonexistent local time resolves to the first valid instant after it; an ambiguous local time fires once at its first occurrence. Epoch fields remain integer seconds." }, "after": { "oneOf": [ { "type": "object", "properties": { "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "condition": { "type": "string", "const": "min_staged_ratio" }, "min_staged_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_errored_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_missing_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "deadline_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "schedule_id", "condition", "min_staged_ratio", "max_errored_ratio", "max_missing_ratio", "deadline_seconds" ], "additionalProperties": false }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "pending", "paused", "completed" ], "default": "pending" } }, "required": [], "additionalProperties": false, "allOf": [ { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "assign" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids" ], "additionalProperties": false } } } }, { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "onboard" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "max_devices" ], "additionalProperties": false } } } } ], "description": "Closed stage-only definition: assign images or onboard the staging agent. Unknown fields at every level are rejected. No install, activation, boot-variable or reload operation exists. Empty target filters and IDs select the whole fleet; explicit IDs intersect filters. Late binding resolves at fire time; early binding retains preview device IDs. A referenced target role must exist. An after gate cannot reference this schedule itself. PATCH replaces supplied top-level subobjects in full, without recursive merge; after:null removes the gate. The resulting complete definition is validated, including compatibility between an omitted existing kind and a supplied payload." }, "examples": { "pause": { "value": { "state": "paused" } }, "removeGate": { "value": { "after": null } }, "retarget": { "value": { "target": { "filters": { "role": "boat" }, "bind": "late" } } } } } } } }, "delete": { "operationId": "management_delete_internal_v1_schedules_id", "summary": "Delete a schedule", "description": "Delete a schedule. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:. Deletion remains allowed when a referenced role or creator is gone.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "example": "s-boat" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "Exactly one singleton field containing the current strong schedule ETag or *. Missing: 428 precondition_required. Weak tags, comma lists, duplicate fields, malformed tags, mixed wildcard/tag values and stale tags: 412 precondition_failed. An item unknown before condition evaluation returns 404. Compare and mutation occur under the schedule shard lock; a revision race returns 412 with the newest current ETag, and a disappearance race returns 412 without an ETag. Other 412 and 428 responses include the current ETag. * matches any existing version and never creates a missing row.", "schema": { "oneOf": [ { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, { "type": "string", "const": "*" } ] }, "example": "\"iris-schedule-s-boat-1\"" } ], "responses": { "204": { "description": "Schedule deleted; empty body", "headers": { "ETag": { "description": "Successfully matched predecessor ETag, including wildcard deletion", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-request" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed" }, "title": { "type": "string" }, "status": { "const": 403 }, "code": { "const": "csrf-validation-failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found or Schedule not found", "x-iris-problem-codes": [ "route-not-found", "schedule_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "schedule_not_found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } }, "schedule_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found", "title": "Schedule not found", "status": 404, "code": "schedule_not_found" } } } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed" }, "title": { "type": "string" }, "status": { "const": 412 }, "code": { "const": "precondition_failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large" }, "title": { "type": "string" }, "status": { "const": 413 }, "code": { "const": "payload-too-large" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid schedule", "x-iris-problem-codes": [ "invalid_schedule" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } } } }, "428": { "description": "Precondition required", "x-iris-problem-codes": [ "precondition_required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required" }, "title": { "type": "string" }, "status": { "const": 428 }, "code": { "const": "precondition_required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Schedule state unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "schedule_state_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/schedules/{id}/occurrences": { "get": { "operationId": "management_get_internal_v1_schedules_id_occurrences", "summary": "List schedule occurrences", "description": "List schedule occurrences. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "example": "s-boat" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum occurrences across this schedule", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "example": 100 }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset in scheduled_at and occurrence-id order", "schema": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807, "default": 0 }, "example": 0 } ], "responses": { "200": { "description": "Schedule-wide occurrence page, ordered by scheduled_at and occurrence id. It retains missed and empty-target outcomes even when they have no per-device receipts or the definition was deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "occurrences": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/ScheduleOccurrence" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "truncated": { "type": "boolean" } }, "required": [ "schedule_id", "occurrences", "total", "offset", "truncated" ], "additionalProperties": false }, "example": { "schedule_id": "s-boat", "occurrences": [ { "id": "6f9753e0d633aab2c497b14f23d9bc21", "schedule_id": "s-boat", "schedule_generation": "00000000000000000000000000000000", "schedule_rev": 1, "schedule": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] } }, "actor": "schedule:s-boat", "slot": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "due", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null }, "scheduled_at": 1788883260, "window_end": 1788886860, "state": "completed", "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "target_snapshot": { "revision": 3, "now": 1788883260, "device_ids": [ "edge-01" ] }, "delta": { "added": 0, "removed": 0 }, "created_at": 1788883260, "updated_at": 1788883300 } ], "total": 1, "offset": 0, "truncated": false } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Route not found or Schedule not found", "x-iris-problem-codes": [ "route-not-found", "schedule_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "schedule_not_found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } }, "schedule_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found", "title": "Schedule not found", "status": 404, "code": "schedule_not_found" } } } } } }, "422": { "description": "Invalid schedule", "x-iris-problem-codes": [ "invalid_schedule" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Schedule state unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "schedule_state_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/schedules/{id}/receipts": { "get": { "operationId": "management_get_internal_v1_schedules_id_receipts", "summary": "List schedule receipts", "description": "List schedule receipts. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "example": "s-boat" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum receipts across this schedule", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 }, "example": 100 }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset in scheduled_at, occurrence_id, device_id order", "schema": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807, "default": 0 }, "example": 0 } ], "responses": { "200": { "description": "Schedule-wide receipt page, ordered by scheduled_at, occurrence_id, device_id. total counts all receipts; truncated is true when offset is nonzero or more rows remain. The response cap never prunes durable evidence.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "receipts": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/ScheduleReceipt" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "truncated": { "type": "boolean" } }, "required": [ "schedule_id", "receipts", "total", "offset", "truncated" ], "additionalProperties": false }, "example": { "schedule_id": "s-boat", "receipts": [ { "occurrence_id": "11111111111111111111111111111111", "device_id": "edge-01", "rev": 1, "attempt": 1, "attempt_started_at": 1788883260, "predecessors": [], "status": "ok", "reason": "assigned", "created_at": 1788883260, "updated_at": 1788883260, "completed_at": 1788883260, "notes": [], "schedule_id": "s-boat", "scheduled_at": 1788883260, "window_end": 1788886860, "occurrence_state": "completed", "schedule_rev": 1, "before_image_ids": [], "after_image_ids": [ "image-a" ], "removed_image_ids": [] } ], "total": 1, "offset": 0, "truncated": false } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "404": { "description": "Route not found or Schedule not found", "x-iris-problem-codes": [ "route-not-found", "schedule_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "schedule_not_found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } }, "schedule_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found", "title": "Schedule not found", "status": 404, "code": "schedule_not_found" } } } } } }, "422": { "description": "Invalid schedule", "x-iris-problem-codes": [ "invalid_schedule" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Schedule state unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "schedule_state_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/internal/v1/schedules/{id}/reaffirm": { "post": { "operationId": "management_post_internal_v1_schedules_id_reaffirm", "summary": "Reaffirm a schedule", "description": "Reaffirm a schedule. Internal HTTPS route; requires the scoped current or previous file-mounted tier credential. Configured API work budgets are shared across Console users and hosts in one management process. Admission follows authentication, CSRF and route checks, before body processing or mutation. HTTP 429 carries Retry-After; stream starts consume one request, not one per event. Login, setup and private tier controls are outside these work budgets. Schedules only assign images or onboard staging agents; devices never evaluate schedule time. Each definition has its own revision, generation and strong ETag; occurrence progress does not change it. Creator existence comes from the current authoritative administrator record, not session expiry. An absent creator is marked but the schedule keeps firing as schedule:. Accepts an empty object only. Replaces created_by with console: derived server-side; identity fields cannot be supplied by the caller.", "tags": [ "management" ], "x-iris-service": "management", "x-iris-security": "managementBearer+consoleSession", "servers": [ { "url": "https://iris-server:9443", "description": "Internal management API" } ], "security": [ { "managementBearer": [], "consoleSession": [], "csrfHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Opaque resource identifier", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "example": "s-boat" }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Constant-time validated token from the console session", "schema": { "type": "string" }, "example": "session-csrf-token" }, { "name": "If-Match", "in": "header", "required": true, "description": "Exactly one singleton field containing the current strong schedule ETag or *. Missing: 428 precondition_required. Weak tags, comma lists, duplicate fields, malformed tags, mixed wildcard/tag values and stale tags: 412 precondition_failed. An item unknown before condition evaluation returns 404. Compare and mutation occur under the schedule shard lock; a revision race returns 412 with the newest current ETag, and a disappearance race returns 412 without an ETag. Other 412 and 428 responses include the current ETag. * matches any existing version and never creates a missing row.", "schema": { "oneOf": [ { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, { "type": "string", "const": "*" } ] }, "example": "\"iris-schedule-s-boat-1\"" } ], "responses": { "200": { "description": "Saved schedule view with server-owned identity and preview", "headers": { "ETag": { "description": "Strong ETag of the returned schedule revision", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/ScheduleView" } }, "required": [ "schedule" ], "additionalProperties": false }, "example": { "schedule": { "kind": "assign", "target": { "filters": { "role": "boat" }, "device_ids": [ "edge-01" ], "bind": "late" }, "payload": { "image_ids": [ "image-a" ], "mode": "merge" }, "when": { "kind": "once", "at": 1788883260, "tz": "UTC", "window_seconds": 3600 }, "state": "pending", "id": "s-boat", "generation": "00000000000000000000000000000000", "rev": 1, "created_by": "console:alice", "created_at": 1788883200, "preview": { "revision": 2, "now": 1788883200, "device_ids": [ "edge-01" ] }, "etag": "\"iris-schedule-s-boat-1\"", "creator_exists": true, "next_fire": { "scheduled_at": 1788883260, "window_end": 1788886860, "status": "future", "resolution": "normal", "tz": "UTC", "local_time": "2026-09-08T16:01:00+00:00", "next_at": null } } } } } }, "400": { "description": "Invalid request", "x-iris-problem-codes": [ "invalid-request" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request" }, "title": { "type": "string" }, "status": { "const": 400 }, "code": { "const": "invalid-request" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid-request", "title": "Invalid request", "status": 400, "code": "invalid-request" } } } }, "401": { "description": "Console session required or Management authentication required", "x-iris-problem-codes": [ "console-session-required", "management-authentication-required" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "console-session-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required" }, "title": { "type": "string" }, "status": { "const": 401 }, "code": { "const": "management-authentication-required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "console-session-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#console-session-required", "title": "Console session required", "status": 401, "code": "console-session-required" } }, "management-authentication-required": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#management-authentication-required", "title": "Management authentication required", "status": 401, "code": "management-authentication-required" } } } } }, "headers": { "WWW-Authenticate": { "description": "Authentication challenge for this service boundary", "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "description": "Csrf validation failed", "x-iris-problem-codes": [ "csrf-validation-failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed" }, "title": { "type": "string" }, "status": { "const": 403 }, "code": { "const": "csrf-validation-failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#csrf-validation-failed", "title": "Csrf validation failed", "status": 403, "code": "csrf-validation-failed" } } } }, "404": { "description": "Route not found or Schedule not found", "x-iris-problem-codes": [ "route-not-found", "schedule_not_found" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "route-not-found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found" }, "title": { "type": "string" }, "status": { "const": 404 }, "code": { "const": "schedule_not_found" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "route-not-found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#route-not-found", "title": "Route not found", "status": 404, "code": "route-not-found" } }, "schedule_not_found": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_not_found", "title": "Schedule not found", "status": 404, "code": "schedule_not_found" } } } } } }, "412": { "description": "Precondition failed", "x-iris-problem-codes": [ "precondition_failed" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed" }, "title": { "type": "string" }, "status": { "const": 412 }, "code": { "const": "precondition_failed" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "413": { "description": "Payload too large", "x-iris-problem-codes": [ "payload-too-large" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large" }, "title": { "type": "string" }, "status": { "const": 413 }, "code": { "const": "payload-too-large" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#payload-too-large", "title": "Payload too large", "status": 413, "code": "payload-too-large" } } } }, "422": { "description": "Invalid schedule", "x-iris-problem-codes": [ "invalid_schedule" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule" }, "title": { "type": "string" }, "status": { "const": 422 }, "code": { "const": "invalid_schedule" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#invalid_schedule", "title": "Invalid schedule", "status": 422, "code": "invalid_schedule" } } } }, "428": { "description": "Precondition required", "x-iris-problem-codes": [ "precondition_required" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required" }, "title": { "type": "string" }, "status": { "const": 428 }, "code": { "const": "precondition_required" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#precondition_required", "title": "Precondition required", "status": 428, "code": "precondition_required" } } }, "headers": { "ETag": { "description": "Current ETag. Present for missing/stale/malformed conditions and revision races; absent on 412 if the row disappeared between the preliminary read and locked mutation.", "schema": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])" }, "example": "\"iris-schedule-s-boat-1\"" } } }, "429": { "description": "Rate limit exceeded", "x-iris-problem-codes": [ "rate-limit-exceeded" ], "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded" }, "title": { "type": "string" }, "status": { "const": 429 }, "code": { "const": "rate-limit-exceeded" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "example": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded" } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Credential store unavailable or Schedule state unavailable or Service unavailable", "x-iris-problem-codes": [ "credential-store-unavailable", "schedule_state_unavailable", "service-unavailable" ], "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "credential-store-unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "schedule_state_unavailable" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable" }, "title": { "type": "string" }, "status": { "const": 503 }, "code": { "const": "service-unavailable" }, "error": { "type": "string", "deprecated": true } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false } ] }, "examples": { "credential-store-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#credential-store-unavailable", "title": "Credential store unavailable", "status": 503, "code": "credential-store-unavailable" } }, "schedule_state_unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#schedule_state_unavailable", "title": "Schedule state unavailable", "status": 503, "code": "schedule_state_unavailable" } }, "service-unavailable": { "value": { "type": "https://cisco-open.github.io/intelligent-release-image-staging/docs/problems/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service-unavailable" } } } } }, "headers": { "Retry-After": { "description": "Seconds before a retry when known", "schema": { "type": "integer", "minimum": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } } } } }, "components": { "securitySchemes": { "consoleSession": { "type": "apiKey", "in": "cookie", "name": "iris_sid", "description": "HttpOnly Secure browser session" }, "consolePassword": { "type": "http", "scheme": "iris-json-password", "description": "Username/password authentication carried by the documented JSON request body, not an HTTP Authorization header", "x-iris-in": "requestBody" }, "setupGrant": { "type": "http", "scheme": "iris-json-setup-grant", "description": "Short-lived one-use setup grant carried by the documented JSON request body", "x-iris-in": "requestBody" }, "csrfHeader": { "type": "apiKey", "in": "header", "name": "X-CSRF-Token", "description": "Required with a console session on mutations" }, "managementBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "scoped opaque token" }, "deviceBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "device catalog token" }, "announceBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "device announce token" }, "legacyAnnounceToken": { "type": "apiKey", "in": "query", "name": "announce_token", "description": "Guest Shell announce query credential" }, "legacyTrackerKey": { "type": "apiKey", "in": "query", "name": "key", "description": "Alternate query credential accepted when Authorization is absent" }, "observabilityBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "scoped observability token" }, "artifactBasic": { "type": "http", "scheme": "basic", "description": "device_id plus resource-bound catalog token" } }, "schemas": { "Problem": { "type": "object", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "code": { "type": "string" }, "error": { "type": "string", "deprecated": true } }, "additionalProperties": true }, "Health": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } }, "additionalProperties": false }, "ScheduleView": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "assign", "onboard" ] }, "target": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "cred": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "management_type": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "model_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "os_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "peer": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "platform": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "q": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "role": { "type": "string", "pattern": "^(?:|__none|[a-z0-9][a-z0-9._-]{0,31})(?![\\s\\S])" }, "status": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "telemetry": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." } }, "required": [], "additionalProperties": false }, "device_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } }, "bind": { "type": "string", "enum": [ "late", "early" ], "default": "late" } }, "required": [ "filters", "device_ids", "bind" ], "additionalProperties": false }, "payload": { "oneOf": [ { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids", "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "telemetry", "telemetry_stream", "mode", "max_devices" ], "additionalProperties": false } ] }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "once" }, "at": { "type": "integer", "minimum": 0, "maximum": 253370159999 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "at", "window_seconds", "tz" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "recurring" }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Monday=0 through Sunday=6" }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "minute": { "type": "integer", "minimum": 0, "maximum": 59 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "weekday", "hour", "minute", "window_seconds", "tz" ], "additionalProperties": false } ], "description": "Server-side half-open window. A nonexistent local time resolves to the first valid instant after it; an ambiguous local time fires once at its first occurrence. Epoch fields remain integer seconds." }, "after": { "type": "object", "properties": { "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "condition": { "type": "string", "const": "min_staged_ratio" }, "min_staged_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_errored_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_missing_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "deadline_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "schedule_id", "condition", "min_staged_ratio", "max_errored_ratio", "max_missing_ratio", "deadline_seconds" ], "additionalProperties": false }, "state": { "type": "string", "enum": [ "pending", "paused", "completed" ], "default": "pending" }, "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "generation": { "type": "string", "pattern": "^[0-9a-f]{32}(?![\\s\\S])" }, "rev": { "type": "integer", "minimum": 1, "maximum": 9223372036854775807 }, "created_by": { "type": "string", "maxLength": 256, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Server-supplied creator identity; ordinary edits preserve it. Reaffirm derives the current actor server-side.", "allOf": [ { "pattern": "^[a-z][a-z0-9_-]{0,31}:.+" } ] }, "created_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "preview": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "now": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "device_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } } }, "required": [ "revision", "now", "device_ids" ], "additionalProperties": false }, "etag": { "type": "string", "pattern": "^\"iris-schedule-[A-Za-z0-9][A-Za-z0-9._-]{0,63}-(?!0)(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])\"(?![\\s\\S])", "readOnly": true }, "creator_exists": { "type": "boolean", "readOnly": true, "description": "Response-only marker from the authoritative administrator record; an absent creator does not prevent firing." }, "next_fire": { "oneOf": [ { "type": "object", "properties": { "scheduled_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "window_end": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "status": { "type": "string", "enum": [ "future", "due", "missed" ] }, "resolution": { "type": "string", "enum": [ "normal", "gap", "fold" ] }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "Valid UTF-8, at most 128 bytes; no leading/trailing whitespace or C0/C1 controls." }, "local_time": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 64, "description": "Valid UTF-8, at most 64 bytes; no leading/trailing whitespace or C0/C1 controls." }, "next_at": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 253370764799 }, { "type": "null" } ] } }, "required": [ "scheduled_at", "window_end", "status", "resolution", "tz", "local_time", "next_at" ], "additionalProperties": false }, { "type": "null" } ], "readOnly": true, "description": "Response-only current or next slot, computed by the same authority the runner fires from, so a client never recomputes local weekly time itself. Null when the schedule is paused or completed, or when a one-time schedule has no further slot." } }, "required": [ "kind", "target", "payload", "when", "state", "id", "generation", "rev", "created_by", "created_at", "preview", "etag", "creator_exists", "next_fire" ], "additionalProperties": false, "allOf": [ { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "assign" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids", "mode" ], "additionalProperties": false } } } }, { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "onboard" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "telemetry", "telemetry_stream", "mode", "max_devices" ], "additionalProperties": false } } } } ], "description": "Closed stage-only definition: assign images or onboard the staging agent. Unknown fields at every level are rejected. No install, activation, boot-variable or reload operation exists. Empty target filters and IDs select the whole fleet; explicit IDs intersect filters. Late binding resolves at fire time; early binding retains preview device IDs. A referenced target role must exist. An after gate cannot reference this schedule itself." }, "StoredSchedule": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "assign", "onboard" ] }, "target": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "cred": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "management_type": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "model_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "os_family": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "peer": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "platform": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "q": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "role": { "type": "string", "pattern": "^(?:|__none|[a-z0-9][a-z0-9._-]{0,31})(?![\\s\\S])" }, "status": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." }, "telemetry": { "type": "string", "maxLength": 256, "minLength": 0, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)?(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls." } }, "required": [], "additionalProperties": false }, "device_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } }, "bind": { "type": "string", "enum": [ "late", "early" ], "default": "late" } }, "required": [ "filters", "device_ids", "bind" ], "additionalProperties": false }, "payload": { "oneOf": [ { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids", "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "telemetry", "telemetry_stream", "mode", "max_devices" ], "additionalProperties": false } ] }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "once" }, "at": { "type": "integer", "minimum": 0, "maximum": 253370159999 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "at", "window_seconds", "tz" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "recurring" }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Monday=0 through Sunday=6" }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "minute": { "type": "integer", "minimum": 0, "maximum": 59 }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "IANA timezone available in server tzdata; defaults to UTC. Unknown names return invalid_schedule.", "default": "UTC" }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "kind", "weekday", "hour", "minute", "window_seconds", "tz" ], "additionalProperties": false } ], "description": "Server-side half-open window. A nonexistent local time resolves to the first valid instant after it; an ambiguous local time fires once at its first occurrence. Epoch fields remain integer seconds." }, "after": { "type": "object", "properties": { "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "condition": { "type": "string", "const": "min_staged_ratio" }, "min_staged_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_errored_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "max_missing_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "deadline_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 } }, "required": [ "schedule_id", "condition", "min_staged_ratio", "max_errored_ratio", "max_missing_ratio", "deadline_seconds" ], "additionalProperties": false }, "state": { "type": "string", "enum": [ "pending", "paused", "completed" ], "default": "pending" }, "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "generation": { "type": "string", "pattern": "^[0-9a-f]{32}(?![\\s\\S])" }, "rev": { "type": "integer", "minimum": 1, "maximum": 9223372036854775807 }, "created_by": { "type": "string", "maxLength": 256, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Server-supplied creator identity; ordinary edits preserve it. Reaffirm derives the current actor server-side.", "allOf": [ { "pattern": "^[a-z][a-z0-9_-]{0,31}:.+" } ] }, "created_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "preview": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "now": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "device_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } } }, "required": [ "revision", "now", "device_ids" ], "additionalProperties": false } }, "required": [ "kind", "target", "payload", "when", "state", "id", "generation", "rev", "created_by", "created_at", "preview" ], "additionalProperties": false, "allOf": [ { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "assign" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "image_ids": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "image_ids", "mode" ], "additionalProperties": false } } } }, { "if": { "required": [ "kind" ], "properties": { "kind": { "const": "onboard" } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "telemetry": { "type": "boolean", "default": true }, "telemetry_stream": { "type": "boolean", "default": false }, "mode": { "type": "string", "const": "new-only", "default": "new-only" }, "max_devices": { "type": "integer", "minimum": 1, "maximum": 20000 } }, "required": [ "telemetry", "telemetry_stream", "mode", "max_devices" ], "additionalProperties": false } } } } ], "description": "Closed stage-only definition: assign images or onboard the staging agent. Unknown fields at every level are rejected. No install, activation, boot-variable or reload operation exists. Empty target filters and IDs select the whole fleet; explicit IDs intersect filters. Late binding resolves at fire time; early binding retains preview device IDs. A referenced target role must exist. An after gate cannot reference this schedule itself." }, "ScheduleOccurrence": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{32}(?![\\s\\S])" }, "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "schedule_generation": { "type": "string", "pattern": "^[0-9a-f]{32}(?![\\s\\S])" }, "schedule_rev": { "type": "integer", "minimum": 1, "maximum": 9223372036854775807 }, "schedule": { "$ref": "#/components/schemas/StoredSchedule" }, "actor": { "type": "string", "maxLength": 256, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 256, "description": "Valid UTF-8, at most 256 bytes; no leading/trailing whitespace or C0/C1 controls.", "allOf": [ { "pattern": "^schedule:[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" } ] }, "slot": { "type": "object", "properties": { "scheduled_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "window_end": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "status": { "type": "string", "enum": [ "future", "due", "missed" ] }, "resolution": { "type": "string", "enum": [ "normal", "gap", "fold" ] }, "tz": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 128, "description": "Valid UTF-8, at most 128 bytes; no leading/trailing whitespace or C0/C1 controls." }, "local_time": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^(?:[^\\s\\x00-\\x1f\\x7f-\\x9f](?:[^\\x00-\\x1f\\x7f-\\x9f]*[^\\s\\x00-\\x1f\\x7f-\\x9f])?)(?![\\s\\S])", "x-iris-maxUtf8Bytes": 64, "description": "Valid UTF-8, at most 64 bytes; no leading/trailing whitespace or C0/C1 controls." }, "next_at": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 253370764799 }, { "type": "null" } ] } }, "required": [ "scheduled_at", "window_end", "status", "resolution", "tz", "local_time", "next_at" ], "additionalProperties": false }, "scheduled_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "window_end": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "state": { "type": "string", "enum": [ "cancelled", "completed", "failed", "interrupted", "missed", "pending", "running", "stalled" ] }, "preview": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "now": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "device_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } }, "registration_ids": { "type": "object", "maxProperties": 20000, "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } }, "additionalProperties": { "oneOf": [ { "type": "string", "pattern": "^[0-9a-f]{32}(?![\\s\\S])" }, { "type": "null" } ] }, "description": "Registration identity for each fired target, frozen when the occurrence is claimed. Legacy snapshots may omit these bindings; new execution requires a durable registration identity." } }, "required": [ "revision", "now", "device_ids" ], "additionalProperties": false }, "created_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "updated_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "target_snapshot": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "now": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "device_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 20000, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } } }, "registration_ids": { "type": "object", "maxProperties": 20000, "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } }, "additionalProperties": { "oneOf": [ { "type": "string", "pattern": "^[0-9a-f]{32}(?![\\s\\S])" }, { "type": "null" } ] }, "description": "Registration identity for each fired target, frozen when the occurrence is claimed. Legacy snapshots may omit these bindings; new execution requires a durable registration identity." } }, "required": [ "revision", "now", "device_ids" ], "additionalProperties": false }, "delta": { "type": "object", "properties": { "added": { "type": "integer", "minimum": 0, "maximum": 20000 }, "removed": { "type": "integer", "minimum": 0, "maximum": 20000 } }, "required": [ "added", "removed" ], "additionalProperties": false }, "annotations": { "type": "object", "properties": { "all_targets_quarantined": { "type": "integer", "minimum": 1, "maximum": 20000 }, "wave": { "type": "object", "properties": { "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "occurrence_id": { "oneOf": [ { "type": "string", "pattern": "^[0-9a-f]{32}(?![\\s\\S])" }, { "type": "null" } ] }, "total": { "type": "integer", "minimum": 0, "maximum": 20000 }, "staged": { "type": "integer", "minimum": 0, "maximum": 20000 }, "errored": { "type": "integer", "minimum": 0, "maximum": 20000 }, "missing": { "type": "integer", "minimum": 0, "maximum": 20000 }, "gate": { "type": "string", "enum": [ "held", "open" ] }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 } }, "required": [ "schedule_id", "occurrence_id", "total", "staged", "errored", "missing", "gate", "observed_at" ], "additionalProperties": false, "description": "Wave-gate evaluation of the preceding schedule's own occurrence: an operational signal about when work is admitted, never an authority over what it may do. staged, errored and missing each count part of that occurrence's bound target and never exceed its total; the remainder is still in flight. Missing counts a device that produced no evidence at all, which is deliberately not the same as errored. A gate with no preceding occurrence yet reports a null occurrence id and zero counts, which is a hold rather than an all-clear." } }, "required": [], "additionalProperties": false } }, "required": [ "id", "schedule_id", "schedule_generation", "schedule_rev", "schedule", "actor", "slot", "scheduled_at", "window_end", "state", "preview", "created_at", "updated_at" ], "additionalProperties": false, "allOf": [ { "if": { "required": [ "state" ], "properties": { "state": { "const": "missed" } } }, "then": { "not": { "anyOf": [ { "required": [ "target_snapshot" ] }, { "required": [ "delta" ] } ] } }, "else": { "required": [ "target_snapshot", "delta" ] } } ], "description": "Durable frozen occurrence authority and outcome. Missed occurrences have no target snapshot or delta; every other state retains both, including an empty target set. Slot resolution records normal, DST-gap or first-fold scheduling." }, "ScheduleReceipt": { "type": "object", "properties": { "occurrence_id": { "type": "string", "pattern": "^[0-9a-f]{32}(?![\\s\\S])" }, "device_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } }, "rev": { "type": "integer", "minimum": 1, "maximum": 9223372036854775807 }, "attempt": { "type": "integer", "minimum": 1, "maximum": 16 }, "attempt_started_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "status": { "type": "string", "enum": [ "error", "intent", "ok", "running", "skipped", "submitted" ] }, "reason": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}(?![\\s\\S])", "description": "Machine-readable per-device outcome. `conflict` includes a current registration that differs from the occurrence binding; `identity_unavailable` means fresh work could not prove a durable target identity. See Operations scheduled outcomes." }, "created_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "updated_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "completed_at": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 253370764799 }, { "type": "null" } ] }, "notes": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}(?![\\s\\S])" }, "maxItems": 16 }, "predecessors": { "type": "array", "maxItems": 15, "items": { "type": "object", "properties": { "occurrence_id": { "type": "string", "pattern": "^[0-9a-f]{32}(?![\\s\\S])" }, "device_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])", "not": { "const": "seeder" } }, "rev": { "type": "integer", "minimum": 1, "maximum": 9223372036854775807 }, "attempt": { "type": "integer", "minimum": 1, "maximum": 16 }, "attempt_started_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "status": { "type": "string", "enum": [ "intent", "submitted", "running" ] }, "reason": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}(?![\\s\\S])", "description": "Machine-readable per-device outcome. `conflict` includes a current registration that differs from the occurrence binding; `identity_unavailable` means fresh work could not prove a durable target identity. See Operations scheduled outcomes." }, "created_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "updated_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "completed_at": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 253370764799 }, { "type": "null" } ] }, "notes": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}(?![\\s\\S])" }, "maxItems": 16 }, "wave": { "type": "object", "properties": { "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "occurrence_id": { "oneOf": [ { "type": "string", "pattern": "^[0-9a-f]{32}(?![\\s\\S])" }, { "type": "null" } ] }, "total": { "type": "integer", "minimum": 0, "maximum": 20000 }, "staged": { "type": "integer", "minimum": 0, "maximum": 20000 }, "errored": { "type": "integer", "minimum": 0, "maximum": 20000 }, "missing": { "type": "integer", "minimum": 0, "maximum": 20000 }, "gate": { "type": "string", "enum": [ "held", "open" ] }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 } }, "required": [ "schedule_id", "occurrence_id", "total", "staged", "errored", "missing", "gate", "observed_at" ], "additionalProperties": false, "description": "Wave-gate evaluation of the preceding schedule's own occurrence: an operational signal about when work is admitted, never an authority over what it may do. staged, errored and missing each count part of that occurrence's bound target and never exceed its total; the remainder is still in flight. Missing counts a device that produced no evidence at all, which is deliberately not the same as errored. A gate with no preceding occurrence yet reports a null occurrence id and zero counts, which is a hold rather than an all-clear." }, "job_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "record_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "predecessor_record_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "manual_generation": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "fleet_registered_at": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 253370764799 }, { "type": "null" } ] }, "fleet_registration_id": { "type": "string", "pattern": "^[0-9a-f]{32}(?![\\s\\S])" }, "before_image_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "after_image_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "removed_image_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } } }, "required": [ "occurrence_id", "device_id", "rev", "attempt", "attempt_started_at", "status", "reason", "created_at", "updated_at", "completed_at", "notes" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "status": { "enum": [ "error", "ok", "skipped" ] } } }, "then": { "properties": { "completed_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 } } }, "else": { "properties": { "completed_at": { "type": "null" } }, "not": { "anyOf": [ { "required": [ "after_image_ids" ] }, { "required": [ "removed_image_ids" ] } ] } } } ], "description": "Durable attempt evidence. Timestamps are ordered created_at <= attempt_started_at <= updated_at; terminal completed_at lies within the attempt. Predecessors retain prior nonterminal attempts without nested history, with increasing revisions and shared device/occurrence identity. The attempt number equals one plus predecessor count. Removed images equal before minus after when all three sets are present." } }, "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "scheduled_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "window_end": { "type": "integer", "minimum": 0, "maximum": 253370764799 }, "occurrence_state": { "type": "string", "enum": [ "cancelled", "completed", "failed", "interrupted", "missed", "pending", "running", "stalled" ] }, "schedule_rev": { "type": "integer", "minimum": 1, "maximum": 9223372036854775807 }, "wave": { "type": "object", "properties": { "schedule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "occurrence_id": { "oneOf": [ { "type": "string", "pattern": "^[0-9a-f]{32}(?![\\s\\S])" }, { "type": "null" } ] }, "total": { "type": "integer", "minimum": 0, "maximum": 20000 }, "staged": { "type": "integer", "minimum": 0, "maximum": 20000 }, "errored": { "type": "integer", "minimum": 0, "maximum": 20000 }, "missing": { "type": "integer", "minimum": 0, "maximum": 20000 }, "gate": { "type": "string", "enum": [ "held", "open" ] }, "observed_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 } }, "required": [ "schedule_id", "occurrence_id", "total", "staged", "errored", "missing", "gate", "observed_at" ], "additionalProperties": false, "description": "Wave-gate evaluation of the preceding schedule's own occurrence: an operational signal about when work is admitted, never an authority over what it may do. staged, errored and missing each count part of that occurrence's bound target and never exceed its total; the remainder is still in flight. Missing counts a device that produced no evidence at all, which is deliberately not the same as errored. A gate with no preceding occurrence yet reports a null occurrence id and zero counts, which is a hold rather than an all-clear." }, "job_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "record_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "predecessor_record_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?![\\s\\S])" }, "manual_generation": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "fleet_registered_at": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 253370764799 }, { "type": "null" } ] }, "fleet_registration_id": { "type": "string", "pattern": "^[0-9a-f]{32}(?![\\s\\S])" }, "before_image_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "after_image_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } }, "removed_image_ids": { "type": "array", "uniqueItems": true, "minItems": 0, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}(?![\\s\\S])" } } }, "required": [ "occurrence_id", "device_id", "rev", "attempt", "attempt_started_at", "status", "reason", "created_at", "updated_at", "completed_at", "notes", "predecessors", "schedule_id", "scheduled_at", "window_end", "occurrence_state", "schedule_rev" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "status": { "enum": [ "error", "ok", "skipped" ] } } }, "then": { "properties": { "completed_at": { "type": "integer", "minimum": 0, "maximum": 253370764799 } } }, "else": { "properties": { "completed_at": { "type": "null" } }, "not": { "anyOf": [ { "required": [ "after_image_ids" ] }, { "required": [ "removed_image_ids" ] } ] } } } ], "description": "Durable attempt evidence. Timestamps are ordered created_at <= attempt_started_at <= updated_at; terminal completed_at lies within the attempt. Predecessors retain prior nonterminal attempts without nested history, with increasing revisions and shared device/occurrence identity. The attempt number equals one plus predecessor count. Removed images equal before minus after when all three sets are present." }, "TrackerQosState": { "type": "object", "additionalProperties": false, "properties": { "announce_min_interval_s": { "type": "integer", "minimum": 10, "maximum": 300 }, "numwant": { "type": "integer", "minimum": 4, "maximum": 200 } } }, "TrackerQosStateMap": { "type": "object", "additionalProperties": false, "properties": { "seeder": { "$ref": "#/components/schemas/TrackerQosState" }, "leecher": { "$ref": "#/components/schemas/TrackerQosState" } }, "description": "Closed seeder and leecher tracker-cadence overrides." } } } }