{ "openapi": "3.1.0", "info": { "title": "Multi SimAdmin Control Plane API", "version": "1.0.0", "description": "Versioned control-plane contract. It exposes registered structured operations, never an arbitrary upstream method/path proxy." }, "servers": [ { "url": "/", "description": "Same-origin control plane; paths already include /api/v1." } ], "paths": { "/api/v1/instances": { "get": { "operationId": "listInstances", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/SortDirection" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["name", "status", "freshness", "updatedAt"] }, "description": "Stable ordering; instance id ascending is the final tie-breaker." }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "capabilityStatus", "in": "query", "schema": { "$ref": "#/components/schemas/CapabilityStatus" } }, { "name": "freshness", "in": "query", "schema": { "$ref": "#/components/schemas/SnapshotFreshness" } }, { "name": "tag", "in": "query", "schema": { "type": "string" } }, { "name": "credentialConfigured", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstancePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "summary": "List registered instances" }, "post": { "operationId": "createInstance", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceInput" } } } }, "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } }, "ETag": { "description": "Opaque entity tag containing the current resource revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Instance" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "summary": "Create a registered instance" } }, "/api/v1/instances/{instanceId}": { "get": { "operationId": "getInstance", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } }, "ETag": { "description": "Opaque entity tag containing the current resource revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Instance" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "summary": "Get a registered instance" }, "patch": { "operationId": "updateInstance", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstancePatch" } } } }, "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } }, "ETag": { "description": "Opaque entity tag containing the current resource revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Instance" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "default": { "$ref": "#/components/responses/Problem" } }, "x-precondition": "A matching If-Match revision is required.", "summary": "Update a registered instance" }, "delete": { "operationId": "deleteInstance", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/PreparationId" }, { "$ref": "#/components/parameters/ConfirmationToken" } ], "responses": { "202": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "default": { "$ref": "#/components/responses/Problem" } }, "x-precondition": "A matching If-Match revision is required.", "description": "R3 deletion cannot execute directly: it requires the one-time token and Preparation id returned by operations/prepare, bound to this instance, revision, and delete operation.", "summary": "Delete a registered instance through confirmed execution" } }, "/api/v1/instances/{instanceId}/test-connection": { "post": { "operationId": "testInstanceConnection", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionMetadata" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "summary": "Test an instance connection" } }, "/api/v1/instances/{instanceId}/login": { "post": { "operationId": "loginInstance", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginInput" } } } }, "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionMetadata" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "summary": "Create an instance authentication session" } }, "/api/v1/instances/{instanceId}/logout": { "post": { "operationId": "logoutInstance", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionMetadata" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "summary": "Clear an instance authentication session" } }, "/api/v1/operations": { "get": { "operationId": "listOperations", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/SortDirection" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["operationId", "risk", "capability"] }, "description": "Stable ordering; operationId ascending is the final tie-breaker." }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "risk", "in": "query", "schema": { "$ref": "#/components/schemas/RiskLevel" } }, { "name": "capability", "in": "query", "schema": { "type": "string" } }, { "name": "batchable", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "summary": "List registered operations" } }, "/api/v1/operations/prepare": { "post": { "operationId": "prepareOperation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareOperationRequest" } } } }, "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preparation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "summary": "Prepare and validate an operation" } }, "/api/v1/operations/execute": { "post": { "operationId": "executePreparedOperation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteOperationRequest" } } } }, "responses": { "202": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "summary": "Execute a prepared operation" } }, "/api/v1/jobs": { "get": { "operationId": "listJobs", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/SortDirection" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["createdAt", "status", "operationId"] }, "description": "Stable ordering; job id ascending is the final tie-breaker." }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/JobStatus" } }, { "name": "operationId", "in": "query", "schema": { "type": "string" } }, { "name": "rootJobId", "in": "query", "schema": { "type": "string" } }, { "name": "instanceId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "summary": "List jobs" } }, "/api/v1/jobs/{jobId}": { "get": { "operationId": "getJob", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "summary": "Get a job" } }, "/api/v1/jobs/{jobId}/cancel": { "post": { "operationId": "cancelJob", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "summary": "Request job cancellation" } }, "/api/v1/jobs/{jobId}/retry": { "post": { "operationId": "retryJob", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryJobRequest" } } } }, "responses": { "202": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "summary": "Retry selected failed job items in a new job" } }, "/api/v1/audit": { "get": { "operationId": "listAuditEvents", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/SortDirection" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["occurredAt", "action", "outcome"] }, "description": "Stable ordering; audit event id ascending is the final tie-breaker." }, { "name": "actorId", "in": "query", "schema": { "type": "string" } }, { "name": "instanceId", "in": "query", "schema": { "type": "string" } }, { "name": "jobId", "in": "query", "schema": { "type": "string" } }, { "name": "operationId", "in": "query", "schema": { "type": "string" } }, { "name": "outcome", "in": "query", "schema": { "$ref": "#/components/schemas/AuditOutcome" } }, { "name": "occurredFrom", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "occurredTo", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "requestId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "summary": "List audit events" } }, "/api/v1/audit/{eventId}": { "get": { "operationId": "getAuditEvent", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEvent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "summary": "Get an audit event" } }, "/api/v1/events": { "get": { "operationId": "streamEvents", "responses": { "200": { "description": "Server-sent control-plane events", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/EventEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } }, "parameters": [ { "$ref": "#/components/parameters/LastEventId" } ], "summary": "Stream control-plane events" } } }, "components": { "schemas": { "Revision": { "type": "integer", "minimum": 1, "description": "Monotonically increasing positive resource revision." }, "CapabilityStatus": { "type": "string", "enum": ["supported", "unsupported", "auth-required", "degraded", "unknown"] }, "SnapshotFreshness": { "type": "string", "enum": ["fresh", "stale", "expired", "unknown"] }, "RiskLevel": { "type": "string", "enum": ["R0", "R1", "R2", "R3"] }, "ValidationIssue": { "type": "object", "additionalProperties": false, "required": ["field", "code", "message"], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string", "description": "Redacted validation message; never contains submitted secret values." } } }, "ProblemDetails": { "type": "object", "additionalProperties": false, "required": ["type", "title", "status", "detail", "code", "requestId"], "properties": { "type": { "type": "string", "format": "uri-reference" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" }, "validation": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationIssue" } } } }, "PageMeta": { "type": "object", "required": ["page", "pageSize", "total"], "properties": { "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "PasswordUpdate": { "description": "Explicit password-reference update. Password is accepted only by the set variant and is never returned.", "oneOf": [ { "type": "object", "additionalProperties": false, "required": ["action"], "properties": { "action": { "const": "preserve" } } }, { "type": "object", "additionalProperties": false, "required": ["action", "password"], "properties": { "action": { "const": "set" }, "password": { "type": "string", "minLength": 1, "writeOnly": true } } }, { "type": "object", "additionalProperties": false, "required": ["action"], "properties": { "action": { "const": "clear" } } } ], "discriminator": { "propertyName": "action" } }, "InstanceInput": { "type": "object", "additionalProperties": false, "required": ["name", "origin"], "properties": { "name": { "type": "string", "minLength": 1 }, "origin": { "type": "string", "format": "uri" }, "tags": { "type": "array", "items": { "type": "string" } }, "password": { "$ref": "#/components/schemas/PasswordUpdate" } } }, "InstancePatch": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1 }, "origin": { "type": "string", "format": "uri" }, "tags": { "type": "array", "items": { "type": "string" } }, "password": { "$ref": "#/components/schemas/PasswordUpdate" } } }, "Instance": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "origin", "tags", "revision", "capabilityStatus", "freshness", "credentialConfigured" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "origin": { "type": "string", "format": "uri" }, "tags": { "type": "array", "items": { "type": "string" } }, "revision": { "$ref": "#/components/schemas/Revision" }, "capabilityStatus": { "$ref": "#/components/schemas/CapabilityStatus" }, "freshness": { "$ref": "#/components/schemas/SnapshotFreshness" }, "credentialConfigured": { "type": "boolean" } } }, "SessionMetadata": { "type": "object", "additionalProperties": false, "required": ["instanceId", "authenticated", "checkedAt"], "properties": { "instanceId": { "type": "string" }, "authenticated": { "type": "boolean" }, "checkedAt": { "type": "string", "format": "date-time" } } }, "LoginInput": { "type": "object", "additionalProperties": false, "properties": { "password": { "type": "string", "minLength": 1, "writeOnly": true } }, "description": "Omit password to resolve a saved reference server-side; supplied password is one-shot input only." }, "OperationCatalogEntry": { "type": "object", "additionalProperties": false, "required": [ "operationId", "title", "risk", "capability", "batchable", "parameterSchemaId" ], "properties": { "operationId": { "type": "string" }, "title": { "type": "string" }, "risk": { "$ref": "#/components/schemas/RiskLevel" }, "capability": { "type": "string" }, "batchable": { "type": "boolean" }, "parameterSchemaId": { "type": "string", "minLength": 1 } }, "description": "Safe metadata projection from OperationRegistry; no upstream path or arbitrary method is exposed." }, "OperationTarget": { "type": "object", "additionalProperties": false, "required": ["instanceId"], "properties": { "instanceId": { "type": "string" }, "revision": { "$ref": "#/components/schemas/Revision" } } }, "PrepareOperationRequest": { "type": "object", "additionalProperties": false, "required": ["operationId", "targets", "parameters"], "properties": { "operationId": { "type": "string" }, "targets": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/OperationTarget" } }, "parameters": { "$ref": "#/components/schemas/RegisteredParameters" } } }, "Preparation": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "operationId", "risk", "expiresAt", "confirmationToken", "confirmationPrompt", "targetCount" ], "properties": { "id": { "type": "string" }, "operationId": { "type": "string" }, "risk": { "$ref": "#/components/schemas/RiskLevel" }, "expiresAt": { "type": "string", "format": "date-time" }, "confirmationPrompt": { "type": "string" }, "targetCount": { "type": "integer", "minimum": 1 }, "status": { "$ref": "#/components/schemas/PreparationStatus" }, "confirmationToken": { "type": "string", "minLength": 20, "description": "Opaque one-time confirmation credential. This is the sole intentional token-valued success response field; never log, audit, persist in browser storage, or return again." } }, "description": "Preflight-only record; it does not create a Job. The response delivers a short-lived one-time confirmationToken consumed with this preparation by execute." }, "ExecuteOperationRequest": { "type": "object", "additionalProperties": false, "required": ["preparationId", "confirmationToken"], "properties": { "preparationId": { "type": "string" }, "confirmationToken": { "type": "string", "writeOnly": true } }, "description": "Execution consumes a preparation-bound confirmation. Dangerous operations cannot bypass prepare." }, "JobStatus": { "type": "string", "enum": [ "queued", "running", "cancelling", "succeeded", "partially-succeeded", "failed", "cancelled", "unknown-result" ], "description": "Transitions: queued -> running|cancelled; running -> cancelling|succeeded|partially-succeeded|failed|unknown-result; cancelling -> cancelled|failed|unknown-result. Terminal states are immutable." }, "JobItemTerminalState": { "type": "string", "enum": ["succeeded", "failed", "skipped", "cancelled", "unknown-result"] }, "JobItem": { "type": "object", "description": "Each item independently reaches one terminal state and may contain its own redacted error.", "required": ["id", "targetId", "state"], "properties": { "id": { "type": "string" }, "targetId": { "type": "string" }, "state": { "$ref": "#/components/schemas/JobItemTerminalState" }, "sourceJobItemId": { "type": "string" }, "error": { "$ref": "#/components/schemas/ProblemDetails" } }, "additionalProperties": false }, "Attempt": { "type": "object", "description": "An Attempt terminal result is immutable. User retry creates a new Job and independent Attempt; bounded transport retries, when allowed, remain internal to this Attempt.", "required": ["id", "state", "startedAt"], "properties": { "id": { "type": "string" }, "state": { "$ref": "#/components/schemas/AttemptStatus" }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "Job": { "type": "object", "description": "Terminal Job state, result, items, Attempts and event history are immutable. User retry always creates a new Job with retryOfJobId and rootJobId; successful items are never replayed.", "required": ["id", "operationId", "status", "rootJobId", "items", "attempts", "createdAt"], "properties": { "id": { "type": "string" }, "operationId": { "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "retryOfJobId": { "type": "string" }, "rootJobId": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/JobItem" } }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/Attempt" } }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "RetryJobRequest": { "type": "object", "additionalProperties": false, "required": ["itemIds", "preparationId", "confirmationToken"], "properties": { "itemIds": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "preparationId": { "type": "string" }, "confirmationToken": { "type": "string", "writeOnly": true } }, "description": "Select only retryable failed items. Creates a new Job; never mutates the source or replays successful items." }, "AuditEvent": { "type": "object", "additionalProperties": false, "required": ["id", "occurredAt", "actorId", "action", "outcome", "requestId"], "properties": { "id": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "actorId": { "type": "string" }, "action": { "type": "string" }, "outcome": { "$ref": "#/components/schemas/AuditOutcome" }, "requestId": { "type": "string" }, "instanceId": { "type": "string" }, "jobId": { "type": "string" }, "parameterSummary": { "type": "array", "items": { "$ref": "#/components/schemas/RedactedParameterSummaryItem" }, "description": "Metadata-only, display-safe summary; never raw request values." }, "itemId": { "type": "string" }, "attemptId": { "type": "string" }, "preparationId": { "type": "string" } } }, "PreparationStatus": { "type": "string", "enum": ["prepared", "consumed", "expired", "invalidated"] }, "AttemptStatus": { "type": "string", "enum": ["running", "succeeded", "failed", "cancelled", "unknown-result"], "description": "Attempt-specific state; it is independent from JobStatus." }, "RegisteredParameters": { "type": "object", "additionalProperties": false, "required": ["parameterSchemaId", "fields"], "properties": { "parameterSchemaId": { "type": "string", "minLength": 1, "description": "Immutable schema id from OperationRegistry." }, "fields": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/RegisteredParameterValue" }, "description": "Structured fields only; duplicate or unknown fieldId values are rejected." } } }, "InstancePage": { "type": "object", "additionalProperties": false, "required": ["items", "page"], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Instance" } }, "page": { "$ref": "#/components/schemas/PageMeta" } } }, "OperationPage": { "type": "object", "additionalProperties": false, "required": ["items", "page"], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OperationCatalogEntry" } }, "page": { "$ref": "#/components/schemas/PageMeta" } } }, "JobPage": { "type": "object", "additionalProperties": false, "required": ["items", "page"], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "page": { "$ref": "#/components/schemas/PageMeta" } } }, "AuditPage": { "type": "object", "additionalProperties": false, "required": ["items", "page"], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "page": { "$ref": "#/components/schemas/PageMeta" } } }, "AuditOutcome": { "type": "string", "enum": ["succeeded", "failed", "partially-succeeded", "denied"] }, "EventEnvelope": { "description": "JSON encoded in each SSE data field. SSE id equals envelope id. Associations allow direct instance/job/item/attempt/audit correlation.", "oneOf": [ { "type": "object", "additionalProperties": false, "required": ["kind", "id", "occurredAt", "requestId", "instanceId"], "properties": { "kind": { "const": "instance" }, "id": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "requestId": { "type": "string" }, "instanceId": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "id", "occurredAt", "requestId", "jobId"], "properties": { "kind": { "const": "job" }, "id": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "requestId": { "type": "string" }, "jobId": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "id", "occurredAt", "requestId", "jobId", "itemId"], "properties": { "kind": { "const": "item" }, "id": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "requestId": { "type": "string" }, "jobId": { "type": "string" }, "itemId": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "id", "occurredAt", "requestId", "jobId", "attemptId"], "properties": { "kind": { "const": "attempt" }, "id": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "requestId": { "type": "string" }, "jobId": { "type": "string" }, "attemptId": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "id", "occurredAt", "requestId", "auditEventId"], "properties": { "kind": { "const": "audit" }, "id": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "requestId": { "type": "string" }, "auditEventId": { "type": "string" } } } ], "discriminator": { "propertyName": "kind" } }, "RegisteredParameterValue": { "description": "One registry-addressed scalar/list field. The registry rejects unknown fieldId values and kind mismatches. Transport fields such as method, path, host, and port are never registered.", "oneOf": [ { "type": "object", "additionalProperties": false, "required": ["fieldId", "kind", "value"], "properties": { "fieldId": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z][A-Za-z0-9_.-]*$" }, "kind": { "const": "string" }, "value": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": ["fieldId", "kind", "value"], "properties": { "fieldId": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z][A-Za-z0-9_.-]*$" }, "kind": { "const": "number" }, "value": { "type": "number" } } }, { "type": "object", "additionalProperties": false, "required": ["fieldId", "kind", "value"], "properties": { "fieldId": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z][A-Za-z0-9_.-]*$" }, "kind": { "const": "boolean" }, "value": { "type": "boolean" } } }, { "type": "object", "additionalProperties": false, "required": ["fieldId", "kind", "value"], "properties": { "fieldId": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z][A-Za-z0-9_.-]*$" }, "kind": { "const": "string-list" }, "value": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": ["fieldId", "kind", "value"], "properties": { "fieldId": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z][A-Za-z0-9_.-]*$" }, "kind": { "const": "number-list" }, "value": { "type": "array", "items": { "type": "number" } } } }, { "type": "object", "additionalProperties": false, "required": ["fieldId", "kind", "value"], "properties": { "fieldId": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z][A-Za-z0-9_.-]*$" }, "kind": { "const": "null" }, "value": { "type": "null" } } } ], "discriminator": { "propertyName": "kind" } }, "RedactedParameterSummaryItem": { "type": "object", "additionalProperties": false, "required": ["fieldId", "displayValue", "redacted"], "properties": { "fieldId": { "type": "string" }, "displayValue": { "type": "string", "description": "Safe display text only; secrets use the canonical redaction marker." }, "redacted": { "type": "boolean" } } } }, "parameters": { "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PageSize": { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "SortDirection": { "name": "direction", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" } }, "IfMatch": { "name": "If-Match", "in": "header", "required": true, "description": "ETag of the resource revision. Mismatch returns 412.", "schema": { "type": "string" } }, "PreparationId": { "name": "X-Preparation-Id", "in": "header", "required": true, "description": "Preparation bound to this exact R3 request.", "schema": { "type": "string", "minLength": 1 } }, "ConfirmationToken": { "name": "X-Confirmation-Token", "in": "header", "required": true, "description": "Opaque, short-lived, one-time confirmation returned by prepare and atomically consumed at execution entry. Sensitive header: never log, audit, trace, or persist.", "schema": { "type": "string", "minLength": 20 }, "x-log-redaction": true }, "LastEventId": { "name": "Last-Event-ID", "in": "header", "required": false, "description": "Resume strictly after this SSE event id. A missing/expired retention position produces a reset event or 409 rather than silently skipping events.", "schema": { "type": "string", "minLength": 1 } } }, "headers": {}, "responses": { "BadRequest": { "description": "Invalid request", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "Resource not found", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PreconditionFailed": { "description": "If-Match revision precondition failed", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Problem": { "description": "Standard control-plane error", "headers": { "X-Request-Id": { "description": "Correlation identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "ControlPlaneSession": { "type": "apiKey", "in": "cookie", "name": "multi_simadmin_session", "description": "HttpOnly, SameSite=Strict control-plane session cookie. The API is same-origin and loopback-bound." } } }, "security": [ { "ControlPlaneSession": [] } ] }