{ "components": { "responses": { "HttpError": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "MethodNotAllowed": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "405: the requested method is unsupported at this path.", "headers": { "Allow": { "description": "Methods accepted at this path.", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "NotFound": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "404: no resource exists at this path.", "headers": { "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "PayloadTooLarge": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "schemas": { "AcceptanceReceipt": { "properties": { "accepted": { "type": "boolean" }, "id": { "format": "uuid", "type": "string" } }, "required": [ "id", "accepted" ], "type": "object" }, "AccessChange": { "additionalProperties": false, "properties": { "allowed": { "description": "True explicitly grants/unblocks; false removes the grant and blocks even open access.", "type": "boolean" }, "expected_generation": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "allowed", "expected_generation" ], "type": "object" }, "AccessDecisionReceipt": { "properties": { "id": { "format": "uuid", "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status" ], "type": "object" }, "AccessMode": { "enum": [ "open", "request", "invite" ], "type": "string" }, "AccessPolicy": { "properties": { "generation": { "format": "int64", "type": "integer" }, "mode": { "$ref": "#/components/schemas/AccessMode" }, "visibility": { "$ref": "#/components/schemas/Visibility" } }, "required": [ "mode", "visibility", "generation" ], "type": "object" }, "AccessPolicyUpdate": { "additionalProperties": false, "properties": { "expected_generation": { "format": "int64", "minimum": 1, "type": "integer" }, "mode": { "enum": [ "open", "request", "invite" ], "type": "string" }, "visibility": { "description": "Omitted or null preserves the model's existing catalogue visibility. Set listed or unlisted explicitly to change it.", "enum": [ "listed", "unlisted", null ], "type": [ "string", "null" ] } }, "required": [ "mode", "expected_generation" ], "type": "object" }, "AccessReceipt": { "properties": { "allowed": { "type": "boolean" }, "generation": { "format": "int64", "type": "integer" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "user_id", "allowed", "generation" ], "type": "object" }, "AccessRequestCreate": { "additionalProperties": false, "properties": { "message": { "default": "", "maxLength": 4000, "type": "string" } }, "type": "object" }, "AccessRequestDecision": { "additionalProperties": false, "properties": { "decision": { "enum": [ "approved", "rejected", "withdrawn" ], "type": "string" } }, "required": [ "decision" ], "type": "object" }, "AccessRequestReceipt": { "properties": { "id": { "format": "uuid", "type": "string" }, "model_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status", "model_id" ], "type": "object" }, "AccessRequestSummary": { "properties": { "created_at": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "message": { "type": "string" }, "resolved_at": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "id", "user_id", "status", "message", "created_at", "resolved_at" ], "type": "object" }, "ArchiveRange": { "additionalProperties": false, "properties": { "byte_length": { "format": "int64", "minimum": 0, "type": "integer" }, "epoch": { "format": "int64", "type": "integer" }, "member": { "type": "string" }, "offset": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "epoch", "offset", "byte_length", "member" ], "type": "object" }, "ArchiveReceipt": { "properties": { "archived": { "type": "boolean" }, "generation": { "format": "int64", "type": "integer" }, "id": { "type": "string" } }, "required": [ "id", "archived", "generation" ], "type": "object" }, "ArchiveSource": { "additionalProperties": false, "properties": { "complete": { "type": "boolean" }, "omitted_bytes": { "format": "int64", "minimum": 0, "type": [ "integer", "null" ] }, "ranges": { "items": { "$ref": "#/components/schemas/ArchiveRange" }, "type": "array" }, "total_bytes": { "format": "int64", "minimum": 0, "type": [ "integer", "null" ] }, "unknown_loss": { "type": "boolean" } }, "required": [ "ranges", "unknown_loss", "complete" ], "type": "object" }, "ArchiveState": { "enum": [ "disabled", "capturing", "pending", "ready", "unavailable", "expired" ], "type": "string" }, "Artifact": { "properties": { "artifact_id": { "format": "uuid", "type": "string" }, "availability": { "$ref": "#/components/schemas/ArtifactAvailability" }, "availability_updated_at": { "type": "string" }, "created_at": { "description": "UTC with PostgreSQL microsecond precision.", "type": "string" }, "created_by_user_id": { "format": "uuid", "type": "string" }, "description": { "$ref": "#/components/schemas/ArtifactDescription" }, "provenance": { "$ref": "#/components/schemas/ArtifactProvenance" } }, "required": [ "artifact_id", "created_by_user_id", "description", "provenance", "availability", "created_at", "availability_updated_at" ], "type": "object" }, "ArtifactAvailability": { "description": "Metadata availability is separate from a producing run's historical outcome.\nReady means an exact version was verified and published. HTTP downloads and\nfile-input authorization remain separate operations.", "enum": [ "pending", "ready", "unavailable", "expired" ], "type": "string" }, "ArtifactContent": { "properties": { "checksum": { "$ref": "#/components/schemas/ObjectChecksum" }, "size_bytes": { "format": "int64", "minimum": 0, "type": "integer" }, "version_id": { "type": "string" } }, "required": [ "version_id", "size_bytes", "checksum" ], "type": "object" }, "ArtifactDescription": { "description": "Description supplied by trusted application code; ownership is never supplied.\nScientific metadata uses the same bounded, exact JSON storage profile as inputs.", "properties": { "logical_name": { "type": "string" }, "media_type": { "description": "A bare type/subtype, without parameters or wildcards.", "type": "string" }, "scientific_metadata": { "description": "An object of scientific annotations, not executable schema/file instructions." }, "storage_destination_id": { "description": "An opaque service-selected destination identity, not a storage URL.", "type": "string" } }, "required": [ "logical_name", "media_type", "scientific_metadata", "storage_destination_id" ], "type": "object" }, "ArtifactDetail": { "allOf": [ { "$ref": "#/components/schemas/Artifact" }, { "properties": { "content": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ArtifactContent", "description": "Verified immutable evidence, retained even after availability is lost.\nNull means no verified version has been bound; it never implies readiness." } ] } }, "type": "object" } ] }, "ArtifactList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ArtifactSummary" }, "type": "array" }, "next_cursor": { "description": "Opaque continuation over the live list, ordered by artifact UUID ascending.", "type": [ "string", "null" ] } }, "required": [ "items" ], "type": "object" }, "ArtifactProducer": { "properties": { "assignment_id": { "format": "uuid", "type": "string" }, "attempt_id": { "format": "uuid", "type": "string" }, "model_id": { "type": "string" }, "publication_id": { "type": "string" }, "run_id": { "format": "uuid", "type": "string" } }, "required": [ "publication_id", "run_id", "model_id", "assignment_id", "attempt_id" ], "type": "object" }, "ArtifactProvenance": { "description": "Uploads belong to their creator. Outputs retain their exact execution producer;\nthe assignment and run already pin the attempt, publication, execution context, and inputs.", "oneOf": [ { "properties": { "kind": { "enum": [ "user_upload" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, { "properties": { "assignment_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "run_output" ], "type": "string" }, "run_id": { "format": "uuid", "type": "string" } }, "required": [ "run_id", "assignment_id", "kind" ], "type": "object" }, { "properties": { "assignment_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "log_archive" ], "type": "string" }, "run_id": { "format": "uuid", "type": "string" } }, "required": [ "run_id", "assignment_id", "kind" ], "type": "object" } ] }, "ArtifactReference": { "additionalProperties": false, "description": "Closed public stored-file reference, never a path or transfer capability.", "properties": { "artifact_id": { "format": "uuid", "pattern": "^(?!00000000-0000-0000-0000-000000000000$)[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } }, "required": [ "artifact_id" ], "type": "object" }, "ArtifactSummary": { "properties": { "artifact_id": { "format": "uuid", "type": "string" }, "availability": { "$ref": "#/components/schemas/ArtifactAvailability" }, "logical_name": { "type": "string" }, "media_type": { "type": "string" }, "size_bytes": { "format": "int64", "minimum": 0, "type": [ "integer", "null" ] } }, "required": [ "artifact_id", "logical_name", "media_type", "availability" ], "type": "object" }, "AssignmentControl": { "additionalProperties": false, "properties": { "allow_launch": { "type": "boolean" }, "cancel_pending": { "type": "boolean" }, "cancel_running": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "allow_launch", "cancel_pending", "cancel_running", "reason" ], "type": "object" }, "AssignmentDetail": { "description": "Immutable original claim receipt beside current progress. No launch authority.\nDeliberately omit Debug because the specification contains private inputs.", "properties": { "assignment": { "$ref": "#/components/schemas/AssignmentReceipt" }, "backend_handle": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BackendHandle", "description": "Immutable backend identity reported for this assignment, if known." } ] }, "delivery_completion": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeliveryCompletionReceipt", "description": "Delivery settlement is independent from the immutable scientific result." } ] }, "last_event_sequence": { "description": "Greatest accepted event sequence, including diagnostic-only events.", "format": "int64", "type": [ "integer", "null" ] }, "last_observed_at": { "description": "API receipt time of the latest qualifying execution observation.", "format": "date-time", "type": [ "string", "null" ] }, "observation_freshness": { "$ref": "#/components/schemas/ObservationFreshness", "description": "API confirmation age: fresh below 60 seconds, stale at or above 60 seconds.\nMissing or future confirmation times are unknown." }, "phase": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RunPhase" } ] }, "resolution": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResolutionSummary", "description": "Safe marker distinguishing operator resolution from connector reporting." } ] }, "result": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RunResult", "description": "Retained terminal result; null while work remains outstanding." } ] }, "state": { "$ref": "#/components/schemas/RunState" } }, "required": [ "assignment", "state", "observation_freshness" ], "type": "object" }, "AssignmentList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AssignmentSummary" }, "type": "array" }, "next_cursor": { "description": "Opaque continuation over a live inventory, oldest assignments first.", "type": [ "string", "null" ] } }, "required": [ "items" ], "type": "object" }, "AssignmentReceipt": { "additionalProperties": false, "description": "Complete pinned specification. Inputs are private; deliberately omit Debug.", "properties": { "assignment_id": { "format": "uuid", "type": "string" }, "attempt_id": { "format": "uuid", "type": "string" }, "connector_id": { "type": "string" }, "context_id": { "type": "string" }, "contract_version": { "format": "int32", "minimum": 0, "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "definition": { "$ref": "#/components/schemas/ScientificDefinition" }, "descriptor": { "$ref": "#/components/schemas/InstallationDescriptor" }, "inputs": {}, "journal_id": { "format": "uuid", "type": "string" }, "model_id": { "type": "string" }, "publication_id": { "description": "Immutable accepted publication and execution context.", "type": "string" }, "requirements": { "$ref": "#/components/schemas/ExecutionRequirements" }, "run_id": { "format": "uuid", "type": "string" }, "storage_destination_id": { "description": "Pinned at acceptance; omitted from historical receipts.", "type": [ "string", "null" ] } }, "required": [ "assignment_id", "run_id", "attempt_id", "connector_id", "journal_id", "model_id", "contract_version", "publication_id", "context_id", "descriptor", "requirements", "definition", "inputs", "created_at" ], "type": "object" }, "AssignmentSummary": { "description": "Bounded identity and progress only; scientific inputs are available in detail.", "properties": { "assignment_id": { "format": "uuid", "type": "string" }, "attempt_id": { "format": "uuid", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "journal_id": { "format": "uuid", "type": "string" }, "phase": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RunPhase" } ] }, "run_id": { "format": "uuid", "type": "string" }, "state": { "$ref": "#/components/schemas/RunState" } }, "required": [ "assignment_id", "run_id", "attempt_id", "journal_id", "state", "created_at" ], "type": "object" }, "AttachmentBody": { "format": "binary", "type": "string" }, "AttemptState": { "enum": [ "pending", "completed", "expired", "cancelled" ], "type": "string" }, "AuditEvent": { "properties": { "action": { "type": "string" }, "actor_id": { "type": "string" }, "actor_kind": { "type": "string" }, "details": {}, "id": { "format": "uuid", "type": "string" }, "occurred_at": { "type": "string" }, "request_id": { "type": [ "string", "null" ] } }, "required": [ "id", "actor_kind", "actor_id", "action", "details", "occurred_at", "request_id" ], "type": "object" }, "Availability": { "properties": { "available": { "type": "boolean" }, "unavailable_reason": { "type": [ "string", "null" ] } }, "required": [ "available", "unavailable_reason" ], "type": "object" }, "AvailableContext": { "properties": { "connection": { "type": "string" }, "driver": { "type": "string" }, "id": { "type": "string" }, "installation_roots": { "items": { "type": "string" }, "type": "array" }, "metadata": { "$ref": "#/components/schemas/ContextMetadata" } }, "required": [ "id", "driver", "connection", "installation_roots", "metadata" ], "type": "object" }, "AvailableGrant": { "properties": { "connector_id": { "type": "string" }, "connector_label": { "type": "string" }, "context": { "$ref": "#/components/schemas/AvailableContext" }, "context_id": { "type": "string" }, "generation": { "format": "int64", "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "max_outstanding_assignments": { "format": "int32", "minimum": 0, "type": "integer" }, "max_queued_runs": { "format": "int32", "minimum": 0, "type": "integer" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "id", "context_id", "connector_id", "connector_label", "user_id", "generation", "max_queued_runs", "max_outstanding_assignments", "context" ], "type": "object" }, "BackendHandle": { "additionalProperties": false, "description": "Backend-defined job identity within the assignment's pinned execution context.\nNamespace distinguishes clusters/accounts that may reuse job identifiers.", "properties": { "job_id": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" }, "namespace": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } }, "required": [ "namespace", "job_id" ], "type": "object" }, "BrowserAuthConfig": { "additionalProperties": false, "properties": { "audience": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "client_id": { "type": "string" }, "issuer": { "type": "string" }, "scopes": { "items": { "type": "string" }, "type": "array" }, "token_endpoint": { "type": "string" } }, "required": [ "issuer", "audience", "client_id", "authorization_endpoint", "token_endpoint", "scopes" ], "type": "object" }, "BuildIdentity": { "additionalProperties": false, "description": "Public executable identity shared by CLI, connector and compute runner.", "properties": { "api": { "type": "string" }, "connector_protocol": { "format": "int32", "minimum": 0, "type": "integer" }, "package": { "type": "string" }, "runner_protocol": { "format": "int32", "minimum": 0, "type": "integer" }, "schema_version": { "format": "int32", "minimum": 0, "type": "integer" }, "source": { "$ref": "#/components/schemas/SourceIdentity" }, "target": { "type": "string" }, "version": { "type": "string" }, "wrapper_protocols": { "items": { "format": "int32", "minimum": 0, "type": "integer" }, "type": "array" } }, "required": [ "schema_version", "package", "version", "target", "source", "api", "connector_protocol", "runner_protocol", "wrapper_protocols" ], "type": "object" }, "CancellationEvent": { "description": "API-owned cancellation facts are bounded to request and confirmation.\nThey repeat on every page independently of the connector observation cursor.", "properties": { "kind": { "type": "string" }, "occurred_at": { "format": "date-time", "type": "string" }, "scope": { "type": "string" } }, "required": [ "kind", "scope", "occurred_at" ], "type": "object" }, "CancellationReceipt": { "additionalProperties": false, "properties": { "cancelled_at": { "description": "Set only after confirmed termination (or cancellation before assignment).", "format": "date-time", "type": [ "string", "null" ] }, "reason": { "description": "The retained actor may be an connector administrator for queued-only cutover.", "type": [ "string", "null" ] }, "requested_at": { "format": "date-time", "type": "string" }, "requested_by_user_id": { "format": "uuid", "type": "string" }, "run_id": { "format": "uuid", "type": "string" }, "scope": { "description": "Creator cancellation covers pending and running work. Connector context-cutover cancellation is queued-only and retains the actual actor and reason.", "enum": [ "pending_and_running", "queued_only" ], "type": "string" }, "state": { "$ref": "#/components/schemas/RunState" }, "status": { "$ref": "#/components/schemas/CancellationStatus" } }, "required": [ "run_id", "requested_by_user_id", "state", "status", "scope", "requested_at" ], "type": "object" }, "CancellationStatus": { "description": "A request does not confirm termination. Completion can win a cancellation race.", "enum": [ "requested", "confirmed", "completed" ], "type": "string" }, "Capability": { "description": "Explicit capabilities understood by this registry version.\nArtifactInputs promises verified staging; ArtifactOutputs promises collection\nand verified publication of declared output files.", "enum": [ "json_inputs", "json_outputs", "artifact_inputs", "artifact_outputs", "large_artifacts", "collection_inputs", "collection_outputs" ], "type": "string" }, "CheckOutcome": { "enum": [ "passed", "failed", "unknown", "not_applicable" ], "type": "string" }, "ChecksumAlgorithm": { "enum": [ "sha256" ], "type": "string" }, "ChecksumType": { "enum": [ "full_object" ], "type": "string" }, "ClaimRequest": { "additionalProperties": false, "description": "Claim parameters are currently empty: the server selects all work by FIFO\neligibility. Process identity is a header and is not semantic claim content.", "type": "object" }, "CollectionBindingReceipt": { "properties": { "artifact_id": { "format": "uuid", "type": "string" }, "version_id": { "type": "string" } }, "required": [ "artifact_id", "version_id" ], "type": "object" }, "CollectionFreezeReceipt": { "properties": { "collection_id": { "format": "uuid", "type": "string" }, "manifest_sha256": { "maxLength": 44, "minLength": 44, "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "type": "string" } }, "required": [ "collection_id", "manifest_sha256" ], "type": "object" }, "CollectionPageReceipt": { "description": "Retained identity and exact range accepted by a member metadata page.", "properties": { "collection_id": { "format": "uuid", "type": "string" }, "count": { "minimum": 0, "type": "integer" }, "start": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "collection_id", "start", "count" ], "type": "object" }, "CollectionReceipt": { "properties": { "collection_id": { "format": "uuid", "type": "string" }, "request": { "$ref": "#/components/schemas/CollectionRequest" } }, "required": [ "collection_id", "request" ], "type": "object" }, "CollectionReference": { "additionalProperties": false, "description": "Closed immutable collection reference used by scientific inputs and results.", "properties": { "collection_id": { "format": "uuid", "pattern": "^(?!00000000-0000-0000-0000-000000000000$)[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } }, "required": [ "collection_id" ], "type": "object" }, "CollectionRequest": { "additionalProperties": false, "properties": { "logical_name": { "type": "string" }, "manifest_sha256": { "maxLength": 44, "minLength": 44, "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "type": "string" }, "member_count": { "format": "int32", "minimum": 0, "type": "integer" }, "output_name": { "type": [ "string", "null" ] }, "scientific_metadata": {}, "total_bytes": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "logical_name", "scientific_metadata", "member_count", "total_bytes", "manifest_sha256" ], "type": "object" }, "CollectionSummary": { "description": "Compact listing; full scientific metadata remains on the collection itself.", "properties": { "available": { "type": "boolean" }, "collection_id": { "format": "uuid", "type": "string" }, "manifest_digest": { "type": [ "string", "null" ] }, "member_count": { "format": "int32", "minimum": 0, "type": "integer" }, "state": { "type": "string" }, "total_bytes": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "collection_id", "state", "member_count", "total_bytes", "available" ], "type": "object" }, "CollectionView": { "allOf": [ { "$ref": "#/components/schemas/CollectionReceipt" }, { "properties": { "available": { "description": "Current tracked member availability. Delivery independently verifies the\nexact storage version; this flag never substitutes for content evidence.", "type": "boolean" }, "manifest_digest": { "maxLength": 44, "minLength": 44, "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "type": [ "string", "null" ] }, "state": { "type": "string" } }, "required": [ "state", "manifest_digest", "available" ], "type": "object" } ] }, "Collection_AccessRequestSummary": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AccessRequestSummary" }, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ], "type": "object" }, "Collection_AuditEvent": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AuditEvent" }, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ], "type": "object" }, "Collection_AvailableGrant": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AvailableGrant" }, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ], "type": "object" }, "Collection_ComputeGrant": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ComputeGrant" }, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ], "type": "object" }, "Collection_ConnectorSummary": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ConnectorSummary" }, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ], "type": "object" }, "Collection_ContextDependency": { "properties": { "items": { "items": { "oneOf": [ { "$ref": "#/components/schemas/PublicationDependency" }, { "$ref": "#/components/schemas/GrantDependency" }, { "$ref": "#/components/schemas/RunDependency" } ] }, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ], "type": "object" }, "Collection_ContextSummary": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ContextSummary" }, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ], "type": "object" }, "Collection_InvitationSummary": { "properties": { "items": { "items": { "$ref": "#/components/schemas/InvitationSummary" }, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ], "type": "object" }, "Collection_ManagedRun": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ManagedRun" }, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ], "type": "object" }, "Collection_OperationalRun": { "properties": { "items": { "items": { "$ref": "#/components/schemas/OperationalRun" }, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ], "type": "object" }, "Collection_PublicationDelegation": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PublicationDelegation" }, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ], "type": "object" }, "Collection_PublicationSummary": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PublicationSummary" }, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ], "type": "object" }, "CompletionBody": { "description": "Existing single-PUT completion and asynchronous multipart intent.", "oneOf": [ { "$ref": "#/components/schemas/UploadCompletionRequest" }, { "$ref": "#/components/schemas/MultipartCompletion" } ] }, "ComputeGrant": { "description": "Current grant policy. Publications retain this identity when limits change.", "properties": { "context_id": { "type": "string" }, "generation": { "format": "int64", "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "max_outstanding_assignments": { "format": "int32", "minimum": 0, "type": "integer" }, "max_queued_runs": { "format": "int32", "minimum": 0, "type": "integer" }, "revoked_at": { "type": [ "string", "null" ] }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "id", "context_id", "user_id", "max_queued_runs", "max_outstanding_assignments", "generation", "revoked_at" ], "type": "object" }, "ConfigurationAcknowledgment": { "additionalProperties": false, "properties": { "validations": { "items": { "additionalProperties": false, "properties": { "generation": { "format": "int64", "minimum": 1, "type": "integer" }, "message": { "maxLength": 1000, "type": [ "string", "null" ] }, "publication_id": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "ready": { "type": "boolean" }, "verified_digests": { "additionalProperties": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "description": "Independently observed file SHA-256 digests, keyed by installation-relative path.", "type": "object" } }, "required": [ "publication_id", "generation", "ready" ], "type": "object" }, "maxItems": 1024, "type": "array" } }, "required": [ "validations" ], "type": "object" }, "ConfigurationCapacity": { "properties": { "counts": { "$ref": "#/components/schemas/ConfigurationCounts" }, "desired_bytes": { "minimum": 0, "type": "integer" }, "maximum_connector_cache_bytes": { "minimum": 0, "type": "integer" }, "maximum_desired_bytes": { "minimum": 0, "type": "integer" }, "maximum_retained_publications": { "minimum": 0, "type": "integer" } }, "required": [ "desired_bytes", "maximum_desired_bytes", "maximum_retained_publications", "maximum_connector_cache_bytes", "counts" ], "type": "object" }, "ConfigurationCounts": { "properties": { "historical_publications": { "format": "int64", "minimum": 0, "type": "integer" }, "retained_publications": { "format": "int64", "minimum": 0, "type": "integer" }, "retired_publications": { "format": "int64", "minimum": 0, "type": "integer" }, "retirement_requested": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "historical_publications", "retained_publications", "retirement_requested", "retired_publications" ], "type": "object" }, "ConfigurationRetentionReceipt": { "additionalProperties": false, "properties": { "configuration_changed": { "description": "Refetch desired configuration before pruning when true.", "type": "boolean" }, "dispositions": { "items": { "additionalProperties": false, "properties": { "context_id": { "maxLength": 200, "minLength": 1, "type": "string" }, "provider_binding_id": { "maxLength": 200, "minLength": 1, "type": "string" }, "state": { "enum": [ "eligible", "retained_reference", "work_or_delivery_pinned", "unmanaged" ], "type": "string" } }, "required": [ "context_id", "provider_binding_id", "state" ], "type": "object" }, "maxItems": 128, "type": "array" }, "generation": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "generation", "configuration_changed", "dispositions" ], "type": "object" }, "ConfigurationRetentionRequest": { "additionalProperties": false, "properties": { "bindings": { "items": { "additionalProperties": false, "properties": { "context_id": { "maxLength": 200, "minLength": 1, "type": "string" }, "provider_binding_id": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "context_id", "provider_binding_id" ], "type": "object" }, "maxItems": 128, "type": "array" } }, "required": [ "bindings" ], "type": "object" }, "ConnectionConfig": { "discriminator": { "mapping": { "direct": "#/components/schemas/DirectConnectionConfig", "ssh": "#/components/schemas/SshConnectionConfig" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/DirectConnectionConfig" }, { "$ref": "#/components/schemas/SshConnectionConfig" } ] }, "ConnectorAlreadyRegistered": { "additionalProperties": false, "properties": { "already_registered": { "type": "boolean" }, "connector_id": { "type": "string" } }, "required": [ "connector_id", "already_registered" ], "type": "object" }, "ConnectorAssignmentPhases": { "properties": { "collecting_results": { "format": "int64", "minimum": 0, "type": "integer" }, "executing": { "format": "int64", "minimum": 0, "type": "integer" }, "preparing": { "format": "int64", "minimum": 0, "type": "integer" }, "uploading_results": { "format": "int64", "minimum": 0, "type": "integer" }, "waiting_for_backend": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "preparing", "waiting_for_backend", "executing", "collecting_results", "uploading_results" ], "type": "object" }, "ConnectorAuthorityChange": { "additionalProperties": false, "properties": { "expected_generation": { "format": "int64", "minimum": 1, "type": "integer" }, "withdrawn": { "type": "boolean" } }, "required": [ "withdrawn", "expected_generation" ], "type": "object" }, "ConnectorBuildObservation": { "properties": { "credential_current": { "type": "boolean" }, "identity": { "$ref": "#/components/schemas/BuildIdentity" }, "received_at": { "type": "string" }, "recent": { "type": "boolean" } }, "required": [ "identity", "received_at", "credential_current", "recent" ], "type": "object" }, "ConnectorContact": { "description": "Recent authenticated contact is independent of process-session ownership.", "properties": { "age_seconds": { "format": "int64", "type": [ "integer", "null" ] }, "assessed_at": { "type": "string" }, "credential_current": { "type": "boolean" }, "freshness": { "$ref": "#/components/schemas/ReportValidity" }, "last_contact_at": { "type": [ "string", "null" ] } }, "required": [ "assessed_at", "freshness", "credential_current" ], "type": "object" }, "ConnectorCreate": { "additionalProperties": false, "properties": { "id": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "label": { "maxLength": 200, "minLength": 1, "type": "string" }, "max_outstanding_assignments": { "default": 4, "maximum": 1024, "minimum": 1, "type": "integer" } }, "required": [ "id", "label" ], "type": "object" }, "ConnectorDiagnostics": { "allOf": [ { "$ref": "#/components/schemas/ConnectorLifecycleStatus" }, { "properties": { "build_observation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConnectorBuildObservation", "description": "Credential-authenticated self-report; neither recency nor identity proves\ncurrent journal ownership or scientific runtime suitability." } ] }, "contact": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConnectorContact" } ] }, "preflight": { "$ref": "#/components/schemas/PreflightSummary" }, "session": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConnectorSessionStatus" } ] }, "setup": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ContextSetupReadiness" } ] }, "unfinished_assignments": { "format": "int64", "type": "integer" } }, "required": [ "unfinished_assignments" ], "type": "object" } ] }, "ConnectorEnrollment": { "additionalProperties": false, "properties": { "connector_id": { "type": "string" }, "enrollment_token": { "type": "string" }, "expires_at": { "type": "string" }, "id": { "format": "uuid", "type": "string" } }, "required": [ "id", "connector_id", "enrollment_token", "expires_at" ], "type": "object" }, "ConnectorLifecycleReceipt": { "properties": { "authority_withdrawn": { "type": "boolean" }, "changed": { "type": "boolean" }, "connector_id": { "type": "string" }, "draining": { "type": "boolean" }, "generation": { "format": "int64", "type": "integer" }, "maintenance_complete": { "type": "boolean" }, "work": { "$ref": "#/components/schemas/ConnectorWorkCounts" } }, "required": [ "connector_id", "generation", "draining", "authority_withdrawn", "changed", "work", "maintenance_complete" ], "type": "object" }, "ConnectorLifecycleStatus": { "properties": { "archived_at": { "type": [ "string", "null" ] }, "authority_withdrawn": { "type": "boolean" }, "configuration_capacity": { "$ref": "#/components/schemas/ConfigurationCapacity" }, "configuration_pending": { "type": "boolean" }, "connector_id": { "type": "string" }, "draining": { "type": "boolean" }, "failed_publications": { "format": "int64", "type": "integer" }, "generation": { "format": "int64", "type": "integer" }, "maintenance_complete": { "type": "boolean" }, "observed_generation": { "format": "int64", "type": "integer" }, "owner_id": { "format": "uuid", "type": "string" }, "ownership_generation": { "format": "int64", "type": "integer" }, "work": { "$ref": "#/components/schemas/ConnectorWorkCounts" } }, "required": [ "connector_id", "owner_id", "ownership_generation", "archived_at", "generation", "observed_generation", "configuration_pending", "draining", "authority_withdrawn", "work", "maintenance_complete", "failed_publications", "configuration_capacity" ], "type": "object" }, "ConnectorRegistration": { "description": "First registration returns a one-time secret; exact retries never mint a replacement.", "oneOf": [ { "$ref": "#/components/schemas/ConnectorEnrollment" }, { "$ref": "#/components/schemas/ConnectorAlreadyRegistered" } ] }, "ConnectorRevocationReceipt": { "properties": { "connector_id": { "type": "string" }, "revoked": { "type": "boolean" } }, "required": [ "connector_id", "revoked" ], "type": "object" }, "ConnectorSessionStatus": { "description": "An open session has no time-based expiry and does not prove a process is alive.", "properties": { "acquired_at": { "type": [ "string", "null" ] }, "open": { "type": "boolean" } }, "required": [ "open" ], "type": "object" }, "ConnectorStateChange": { "additionalProperties": false, "properties": { "draining": { "type": "boolean" }, "expected_generation": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "draining", "expected_generation" ], "type": "object" }, "ConnectorSummary": { "properties": { "archived_at": { "type": [ "string", "null" ] }, "authority_withdrawn": { "type": "boolean" }, "connector_id": { "type": "string" }, "draining": { "type": "boolean" }, "generation": { "format": "int64", "type": "integer" }, "label": { "type": "string" }, "max_outstanding_assignments": { "format": "int32", "minimum": 0, "type": "integer" }, "observed_generation": { "format": "int64", "type": "integer" }, "owner_id": { "format": "uuid", "type": "string" }, "ownership_generation": { "format": "int64", "type": "integer" } }, "required": [ "connector_id", "owner_id", "ownership_generation", "archived_at", "label", "generation", "observed_generation", "draining", "authority_withdrawn", "max_outstanding_assignments" ], "type": "object" }, "ConnectorUpdate": { "additionalProperties": false, "properties": { "expected_generation": { "format": "int64", "minimum": 1, "type": "integer" }, "label": { "maxLength": 200, "minLength": 1, "type": "string" }, "max_outstanding_assignments": { "maximum": 1024, "minimum": 1, "type": "integer" } }, "required": [ "label", "max_outstanding_assignments", "expected_generation" ], "type": "object" }, "ConnectorUpdateReceipt": { "properties": { "connector_id": { "type": "string" }, "generation": { "format": "int64", "type": "integer" }, "label": { "type": "string" }, "max_outstanding_assignments": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "connector_id", "label", "max_outstanding_assignments", "generation" ], "type": "object" }, "ConnectorWorkCounts": { "description": "Counts describe durable service evidence, never scientific inputs or results.", "properties": { "assignment_phases": { "$ref": "#/components/schemas/ConnectorAssignmentPhases" }, "pending_delivery_assignments": { "format": "int64", "minimum": 0, "type": "integer" }, "pending_log_archives": { "format": "int64", "minimum": 0, "type": "integer" }, "pending_uploads": { "format": "int64", "minimum": 0, "type": "integer" }, "retained_queued_runs": { "format": "int64", "minimum": 0, "type": "integer" }, "unconfirmed_assignments": { "description": "A subset of unfinished assignments; stale contact cannot prove completion.", "format": "int64", "minimum": 0, "type": "integer" }, "unfinished_assignments": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "retained_queued_runs", "unfinished_assignments", "pending_delivery_assignments", "pending_uploads", "pending_log_archives", "unconfirmed_assignments", "assignment_phases" ], "type": "object" }, "ContextAcceptedWorkPolicy": { "enum": [ "drain", "cancel_queued" ], "type": "string" }, "ContextCreate": { "additionalProperties": false, "properties": { "connector_id": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "definition": { "$ref": "#/components/schemas/ExecutionContextDefinition" }, "id": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "metadata": { "$ref": "#/components/schemas/ContextMetadata" } }, "required": [ "id", "connector_id", "definition", "metadata" ], "type": "object" }, "ContextCutover": { "additionalProperties": false, "properties": { "accepted_work": { "$ref": "#/components/schemas/ContextAcceptedWorkPolicy" }, "expected_generation": { "format": "int64", "minimum": 1, "type": "integer" }, "replacement_context_id": { "description": "Optional fresh active context ID on a connector administered by the caller. This records the handoff without moving accepted work.", "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": [ "string", "null" ] } }, "required": [ "expected_generation", "accepted_work" ], "type": "object" }, "ContextDependencySection": { "default": "publications", "enum": [ "publications", "grants", "runs" ], "type": "string" }, "ContextLifecycleReceipt": { "properties": { "cancelled_queued_runs": { "format": "int64", "type": "integer" }, "context": { "$ref": "#/components/schemas/ContextLifecycleStatus" }, "operation": { "type": "string" }, "requested_publications": { "format": "int64", "type": "integer" } }, "required": [ "operation", "context", "cancelled_queued_runs", "requested_publications" ], "type": "object" }, "ContextLifecycleState": { "description": "Operational lifecycle; the immutable execution definition never changes.", "enum": [ "active", "draining", "retired" ], "type": "string" }, "ContextLifecycleStatus": { "properties": { "accepted_work": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ContextAcceptedWorkPolicy" } ] }, "configuration_removal_generation": { "format": "int64", "type": [ "integer", "null" ] }, "connector_generation": { "format": "int64", "type": "integer" }, "connector_id": { "type": "string" }, "connector_work": { "$ref": "#/components/schemas/ConnectorWorkCounts" }, "generation": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "live_current_publications": { "format": "int64", "type": "integer" }, "local_cleanup_state": { "type": "string" }, "observed_generation": { "format": "int64", "type": "integer" }, "pending_configuration_retirements": { "format": "int64", "type": "integer" }, "replacement_context_id": { "type": [ "string", "null" ] }, "retained_publications": { "format": "int64", "type": "integer" }, "retirement_ready": { "type": "boolean" }, "state": { "$ref": "#/components/schemas/ContextLifecycleState" }, "work": { "$ref": "#/components/schemas/ConnectorWorkCounts" } }, "required": [ "id", "connector_id", "generation", "state", "replacement_context_id", "accepted_work", "work", "live_current_publications", "retained_publications", "pending_configuration_retirements", "configuration_removal_generation", "connector_generation", "observed_generation", "retirement_ready", "connector_work", "local_cleanup_state" ], "type": "object" }, "ContextMetadata": { "additionalProperties": false, "properties": { "disclosure": { "description": "Connector data-access disclosure, 1–3800 UTF-8 bytes without surrounding whitespace or controls.", "maxLength": 3800, "minLength": 1, "type": "string" }, "location": { "description": "Descriptive location, 1–200 UTF-8 bytes without surrounding whitespace or controls.", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "location", "disclosure" ], "type": "object" }, "ContextMetadataReceipt": { "properties": { "generation": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/ContextMetadata" } }, "required": [ "id", "metadata", "generation" ], "type": "object" }, "ContextMetadataUpdate": { "additionalProperties": false, "properties": { "expected_generation": { "format": "int64", "minimum": 1, "type": "integer" }, "metadata": { "$ref": "#/components/schemas/ContextMetadata" } }, "required": [ "metadata", "expected_generation" ], "type": "object" }, "ContextPreflightStatus": { "properties": { "attempt": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PreflightAttempt" } ] }, "connector_id": { "type": "string" }, "context_id": { "type": "string" }, "definition_hash": { "type": "string" }, "ownership_generation": { "format": "int64", "type": "integer" }, "ready": { "type": "boolean" }, "reason": { "type": "string" }, "report": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HostPreflightReport" } ] }, "validity": { "$ref": "#/components/schemas/ReportValidity" } }, "required": [ "connector_id", "context_id", "definition_hash", "ownership_generation", "validity", "reason", "ready" ], "type": "object" }, "ContextRegistration": { "properties": { "connector_id": { "type": "string" }, "definition": { "$ref": "#/components/schemas/ExecutionContextDefinition" }, "generation": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/ContextMetadata" } }, "required": [ "id", "connector_id", "definition", "metadata", "generation" ], "type": "object" }, "ContextReplacementPlan": { "properties": { "actions": { "items": { "$ref": "#/components/schemas/ReplacementAction" }, "type": "array" }, "context": { "$ref": "#/components/schemas/ContextLifecycleStatus" }, "dependencies": { "$ref": "#/components/schemas/Collection_ContextDependency" }, "replacement": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReplacementContext" } ] } }, "required": [ "context", "replacement", "dependencies", "actions" ], "type": "object" }, "ContextSetupReadiness": { "description": "Setup prerequisites, never publication, grant or scientific qualification.", "properties": { "archived": { "type": "boolean" }, "configured": { "type": "boolean" }, "connected": { "type": "boolean" }, "context_id": { "type": "string" }, "issues": { "items": { "$ref": "#/components/schemas/SetupIssue" }, "type": "array" }, "lifecycle_state": { "$ref": "#/components/schemas/ContextLifecycleState" }, "preflight": { "$ref": "#/components/schemas/ContextPreflightStatus" }, "ready": { "type": "boolean" } }, "required": [ "context_id", "lifecycle_state", "archived", "configured", "connected", "ready", "preflight", "issues" ], "type": "object" }, "ContextSummary": { "properties": { "connector_id": { "type": "string" }, "definition": { "$ref": "#/components/schemas/ExecutionContextDefinition" }, "generation": { "format": "int64", "type": [ "integer", "null" ] }, "id": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/ContextMetadata" }, "state": { "$ref": "#/components/schemas/ContextLifecycleState" } }, "required": [ "id", "connector_id", "definition", "metadata", "state", "generation" ], "type": "object" }, "CreateToken": { "additionalProperties": false, "properties": { "expires_in_seconds": { "format": "int64", "maximum": 31536000, "minimum": 1, "type": "integer" }, "name": { "description": "1–200 UTF-8 bytes without surrounding whitespace or control characters.", "maxLength": 200, "minLength": 1, "type": "string" }, "scopes": { "items": { "enum": [ "me:read", "models:read", "models:manage", "runs:create", "runs:read", "runs:cancel", "uploads:create", "uploads:read", "uploads:complete", "artifacts:read", "artifacts:download", "connectors:read", "connectors:manage", "access:manage", "tokens:manage", "audit:read", "service:read", "service:manage" ], "type": "string" }, "maxItems": 18, "minItems": 1, "type": "array" } }, "required": [ "name", "scopes", "expires_in_seconds" ], "type": "object" }, "CurrentPublication": { "properties": { "available": { "type": "boolean" }, "context_id": { "type": "string" }, "definition": { "$ref": "#/components/schemas/ScientificDefinition" }, "disclosure": { "type": "string" }, "execution_location": { "type": "string" }, "id": { "type": "string" }, "installation_revoked_at": { "type": [ "string", "null" ] }, "publication_id": { "type": "string" }, "revoked_at": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "submission_availability": { "$ref": "#/components/schemas/SubmissionAvailability" } }, "required": [ "id", "publication_id", "definition", "disclosure", "execution_location", "revoked_at", "installation_revoked_at", "context_id", "status", "available", "submission_availability" ], "type": "object" }, "DeliveryCompletionReceipt": { "additionalProperties": false, "properties": { "assignment_id": { "format": "uuid", "type": "string" }, "attempt_id": { "format": "uuid", "type": "string" }, "completed_at": { "format": "date-time", "type": "string" }, "run_id": { "format": "uuid", "type": "string" }, "source": { "description": "`connector` accounts for normal delivery; `operator_abandonment` records loss.", "type": "string" } }, "required": [ "assignment_id", "run_id", "attempt_id", "source", "completed_at" ], "type": "object" }, "DeliveryCompletionRequest": { "additionalProperties": false, "properties": { "archive_expected": { "description": "True when this assignment has a configured archive to publish or abandon.", "type": "boolean" }, "attempt_id": { "format": "uuid", "type": "string" } }, "required": [ "attempt_id", "archive_expected" ], "type": "object" }, "DesiredConfiguration": { "additionalProperties": false, "properties": { "contexts": { "items": { "additionalProperties": false, "properties": { "definition": { "$ref": "#/components/schemas/ExecutionContextDefinition" }, "id": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" } }, "required": [ "id", "definition" ], "type": "object" }, "type": "array" }, "generation": { "format": "int64", "minimum": 1, "type": "integer" }, "publications": { "items": { "additionalProperties": false, "properties": { "context_id": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "descriptor": { "$ref": "#/components/schemas/InstallationDescriptor" }, "generation": { "format": "int64", "minimum": 1, "type": "integer" }, "publication_id": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "requirements": { "$ref": "#/components/schemas/ExecutionRequirements" } }, "required": [ "publication_id", "context_id", "generation", "descriptor", "requirements" ], "type": "object" }, "maxItems": 1024, "type": "array" }, "run_payload_namespace_reserved": { "default": false, "description": "True only when new registrations reject release directories and declared entrypoint/batch files inside any known context work_root/UUID subtree. Missing or false on an older service does not establish payload-cleanup protection.", "type": "boolean" } }, "required": [ "generation", "contexts", "publications" ], "type": "object" }, "Diagnostic": { "additionalProperties": false, "description": "Private retained text, never an operational trace field or a terminal result.", "properties": { "code": { "maxLength": 64, "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$", "type": "string" }, "level": { "$ref": "#/components/schemas/DiagnosticLevel" }, "message": { "description": "At most 2048 UTF-8 bytes; only tab and newline control characters allowed.", "maxLength": 2048, "minLength": 1, "type": "string" } }, "required": [ "level", "code", "message" ], "type": "object" }, "DiagnosticLevel": { "enum": [ "info", "warning", "error" ], "type": "string" }, "DirectConnectionConfig": { "additionalProperties": false, "properties": { "kind": { "enum": [ "direct" ], "type": "string" }, "launcher": { "description": "Absolute runner launcher argv. Managed execution requires a separate identity; development requires explicit host consent and the same non-root UID.", "items": { "type": "string" }, "maxItems": 32, "minItems": 1, "type": "array" } }, "required": [ "kind", "launcher" ], "type": "object" }, "DriverConfig": { "description": "New process contexts require scratch. Omitted only in retained legacy contexts and their exact registration retries.", "discriminator": { "mapping": { "process": "#/components/schemas/ProcessDriverConfig", "slurm": "#/components/schemas/SlurmDriverConfig" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/ProcessDriverConfig" }, { "$ref": "#/components/schemas/SlurmDriverConfig" } ] }, "EnrollmentReceipt": { "additionalProperties": false, "properties": { "connector_id": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "credential_id": { "format": "uuid", "type": "string" } }, "required": [ "connector_id", "credential_id" ], "type": "object" }, "EnrollmentRequest": { "additionalProperties": false, "properties": { "credential_id": { "format": "uuid", "type": "string" }, "enrollment_token": { "maxLength": 43, "minLength": 43, "type": "string", "writeOnly": true }, "machine_id": { "format": "uuid", "type": "string" }, "token_verifier": { "description": "SHA-256 of the entire locally generated connector bearer token.", "pattern": "^[0-9a-f]{64}$", "type": "string" } }, "required": [ "enrollment_token", "machine_id", "credential_id", "token_verifier" ], "type": "object" }, "ErrorResponse": { "description": "The common JSON body for errors returned by the HTTP application.", "properties": { "code": { "description": "Stable machine-readable error code.", "type": "string" }, "details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ValidationDetails", "description": "Bounded corrections for authorized scientific-schema failures only.\nAbsent on other failures. The complete validation error body is <=4608 bytes." } ] }, "message": { "description": "Safe explanation without internal errors or submitted input values.", "type": "string" }, "request_id": { "description": "Matches the response's `x-request-id` header.", "type": "string" } }, "required": [ "code", "message", "request_id" ], "type": "object" }, "EventDisposition": { "enum": [ "applied", "stale" ], "type": "string" }, "EventEntry": { "properties": { "position": { "format": "int64", "type": "integer" }, "receipt": { "$ref": "#/components/schemas/EventReceipt" }, "request": { "$ref": "#/components/schemas/EventRequest" } }, "required": [ "position", "request", "receipt" ], "type": "object" }, "EventHistory": { "properties": { "cancellation_events": { "items": { "$ref": "#/components/schemas/CancellationEvent" }, "type": "array" }, "items": { "items": { "$ref": "#/components/schemas/EventEntry" }, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] }, "resume_cursor": { "type": "string" }, "retention": { "$ref": "#/components/schemas/RetentionBoundary" } }, "required": [ "cancellation_events", "items", "resume_cursor", "retention" ], "type": "object" }, "EventReceipt": { "description": "Immutable acknowledgement, not a current-state response. Replays preserve it.", "properties": { "assignment_id": { "format": "uuid", "type": "string" }, "disposition": { "$ref": "#/components/schemas/EventDisposition" }, "event_id": { "format": "uuid", "type": "string" }, "observation_confirmed": { "type": "boolean" }, "phase": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RunPhase" } ] }, "received_at": { "format": "date-time", "type": "string" }, "sequence": { "format": "int64", "type": "integer" } }, "required": [ "assignment_id", "event_id", "sequence", "disposition", "received_at", "observation_confirmed" ], "type": "object" }, "EventRequest": { "additionalProperties": false, "properties": { "attempt_id": { "format": "uuid", "type": "string" }, "backend_handle": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BackendHandle" } ] }, "diagnostic": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Diagnostic" } ] }, "observed_at": { "description": "Actual evidence capture time, not retry time. Never used as server time.", "format": "date-time", "type": "string" }, "phase": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RunPhase" } ] }, "sequence": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "attempt_id", "sequence", "observed_at" ], "type": "object" }, "ExecutionAuthorizationReason": { "enum": [ "model_access_revoked", "compute_access_revoked", "compute_unavailable", "publication_revoked", "installation_revoked" ], "type": "string" }, "ExecutionContextDefinition": { "additionalProperties": false, "properties": { "connection": { "$ref": "#/components/schemas/ConnectionConfig" }, "driver": { "$ref": "#/components/schemas/DriverConfig" }, "execution_mode": { "default": "managed", "description": "Development permits trusted same-user execution only with process/direct and explicit connector host opt-in. Model code can access that user's connector credentials and files.", "enum": [ "managed", "development" ], "type": "string" }, "installation_roots": { "items": { "type": "string" }, "maxItems": 32, "minItems": 1, "type": "array" }, "max_outstanding_assignments": { "maximum": 1024, "minimum": 1, "type": "integer" }, "shared_workspace": { "additionalProperties": false, "properties": { "connector_root": { "type": "string" }, "runner_root": { "type": "string" } }, "required": [ "runner_root", "connector_root" ], "type": "object" }, "work_root": { "type": "string" } }, "required": [ "driver", "connection", "installation_roots", "work_root", "max_outstanding_assignments" ], "type": "object" }, "ExecutionControl": { "description": "A live control diagnostic, not proof that a remote cancellation succeeded.", "properties": { "authorization_reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExecutionAuthorizationReason", "description": "Current authorization failure; retained as context even after completion." } ] }, "state": { "$ref": "#/components/schemas/ExecutionControlState" } }, "required": [ "state" ], "type": "object" }, "ExecutionControlState": { "enum": [ "authorized", "blocked", "cancellation_pending", "draining", "completed" ], "type": "string" }, "ExecutionDestination": { "properties": { "context_id": { "type": "string" }, "disclosure": { "type": "string" }, "execution_location": { "type": "string" } }, "required": [ "context_id", "execution_location", "disclosure" ], "type": "object" }, "ExecutionDriver": { "description": "Execution mechanisms, independent of the wrapper's request/result protocol.", "enum": [ "process", "slurm" ], "type": "string" }, "ExecutionProvenance": { "description": "Public projection of the original claim receipt and immutable backend handle.\nProcess sessions, journal IDs and provider-local launch selectors are omitted.", "properties": { "assigned_at": { "format": "date-time", "type": "string" }, "assignment_id": { "format": "uuid", "type": "string" }, "attempt_id": { "format": "uuid", "type": "string" }, "backend_handle": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BackendHandle" } ] }, "connector_id": { "type": "string" }, "context_id": { "type": "string" }, "installation": { "$ref": "#/components/schemas/InstallationIdentity" }, "last_observed_at": { "format": "date-time", "type": [ "string", "null" ] }, "requirements": { "$ref": "#/components/schemas/ExecutionRequirements" } }, "required": [ "assignment_id", "attempt_id", "connector_id", "context_id", "installation", "requirements", "assigned_at" ], "type": "object" }, "ExecutionRequirements": { "additionalProperties": false, "description": "Requirements derived from an immutable context and scientific contract.\nThese are execution needs, not observations of backend support.", "properties": { "capabilities": { "items": { "$ref": "#/components/schemas/Capability" }, "type": "array" }, "driver": { "$ref": "#/components/schemas/ExecutionDriver" }, "wrapper_protocol_version": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "driver", "capabilities", "wrapper_protocol_version" ], "type": "object" }, "ExecutionStatus": { "enum": [ "never_started", "terminated" ], "type": "string" }, "GenerationChange": { "additionalProperties": false, "properties": { "expected_generation": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "expected_generation" ], "type": "object" }, "GrantCreate": { "additionalProperties": false, "properties": { "context_id": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "id": { "description": "Optional non-nil durable creation identity. Exact retries reuse this active grant; revoked identities and conflicting requests cannot create replacement authority.", "format": "uuid", "type": "string" }, "max_outstanding_assignments": { "default": 4, "maximum": 1024, "minimum": 1, "type": "integer" }, "max_queued_runs": { "default": 100, "maximum": 10000, "minimum": 1, "type": "integer" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "context_id", "user_id" ], "type": "object" }, "GrantDependency": { "properties": { "context_id": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "max_outstanding_assignments": { "format": "int32", "minimum": 0, "type": "integer" }, "max_queued_runs": { "format": "int32", "minimum": 0, "type": "integer" }, "revoked_at": { "type": [ "string", "null" ] }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "id", "context_id", "user_id", "max_queued_runs", "max_outstanding_assignments", "revoked_at" ], "type": "object" }, "GrantUpdate": { "additionalProperties": false, "properties": { "expected_generation": { "format": "int64", "minimum": 1, "type": "integer" }, "max_outstanding_assignments": { "maximum": 1024, "minimum": 1, "type": "integer" }, "max_queued_runs": { "maximum": 10000, "minimum": 1, "type": "integer" } }, "required": [ "expected_generation", "max_queued_runs", "max_outstanding_assignments" ], "type": "object" }, "HeartbeatReceipt": { "properties": { "connector_id": { "type": "string" }, "heartbeat_interval_seconds": { "format": "int32", "minimum": 0, "type": "integer" }, "received_at": { "description": "Server time of the serialized write, returned only after commit.", "format": "date-time", "type": "string" }, "stale_after_seconds": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "connector_id", "received_at", "heartbeat_interval_seconds", "stale_after_seconds" ], "type": "object" }, "HeartbeatRequest": { "additionalProperties": false, "description": "Declared support is observational. Only authorized publications and pinned\nassignment requirements can authorize later execution.", "properties": { "build_identity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BuildIdentity", "description": "Embedded build observed in the reporting process, not the current file at its path." } ] }, "capabilities": { "description": "Unique identifiers; future names are retained without granting support.", "items": { "type": "string" }, "maxItems": 32, "type": "array" }, "connector_version": { "description": "Software build label, not a wrapper or connector wire-protocol version.", "maxLength": 100, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" }, "wrapper_protocol_versions": { "description": "Unique positive version numbers. Empty means no wrapper support reported.", "items": { "format": "int32", "minimum": 0, "type": "integer" }, "maxItems": 16, "type": "array" } }, "required": [ "connector_version", "capabilities", "wrapper_protocol_versions" ], "type": "object" }, "HostCheck": { "additionalProperties": false, "properties": { "check": { "type": "string" }, "code": { "type": "string" }, "correction": { "type": "string" }, "outcome": { "$ref": "#/components/schemas/CheckOutcome" }, "required": { "type": "boolean" }, "responsible_role": { "$ref": "#/components/schemas/ResponsibleRole" } }, "required": [ "check", "outcome", "required", "code", "responsible_role", "correction" ], "type": "object" }, "HostPreflightReport": { "additionalProperties": false, "properties": { "checks": { "items": { "$ref": "#/components/schemas/HostCheck" }, "type": "array" }, "connector_id": { "type": "string" }, "context_id": { "type": "string" }, "definition_hash": { "type": "string" }, "execution_mode": { "type": "string" }, "execution_uid": { "type": [ "string", "null" ] }, "limitations": { "items": { "type": "string" }, "type": "array" }, "manifest_version": { "format": "int32", "minimum": 0, "type": "integer" }, "observed_at": { "type": "string" }, "probe_id": { "format": "uuid", "type": [ "string", "null" ] }, "request_id": { "format": "uuid", "type": "string" }, "source": { "$ref": "#/components/schemas/ReportSource" } }, "required": [ "manifest_version", "request_id", "connector_id", "context_id", "definition_hash", "execution_mode", "observed_at", "source", "checks", "limitations" ], "type": "object" }, "InputRule": { "description": "Stable categories independent of the validator's free-form diagnostics.", "enum": [ "type", "required", "additionalProperties", "propertyNames", "unevaluatedProperties", "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf", "minLength", "maxLength", "pattern", "format", "enum", "const", "minItems", "maxItems", "uniqueItems", "additionalItems", "unevaluatedItems", "contains", "minProperties", "maxProperties", "anyOf", "oneOf", "not", "contentEncoding", "contentMediaType", "schema" ], "type": "string" }, "InputViolation": { "description": "A schema failure without submitted values or arbitrary property names.", "properties": { "correction": { "description": "Fixed guidance; actual bounds and allowed values remain in the publication schema.", "maxLength": 160, "type": "string" }, "position": { "description": "JSON Pointer relative to `inputs`; the empty string denotes its root.\nOnly ordinary, explicitly declared property names and array indices appear.", "example": "/value", "maxLength": 128, "type": "string" }, "position_redacted": { "description": "The position stops at a safe ancestor instead of naming the exact field.", "type": "boolean" }, "rule": { "$ref": "#/components/schemas/InputRule" } }, "required": [ "position", "position_redacted", "rule", "correction" ], "type": "object" }, "InstallationDescriptor": { "additionalProperties": false, "description": "Internal registration snapshot used by connector configuration and execution evidence.", "properties": { "entrypoint": { "description": "First argument is an executable path relative to release_path.", "items": { "type": "string" }, "type": "array" }, "environment": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "installation": { "$ref": "#/components/schemas/InstallationIdentity" }, "provider_binding_id": { "type": "string" }, "release_path": { "type": "string" }, "slurm_script": { "description": "Model-supplied batch file relative to release_path; required for Slurm.", "type": [ "string", "null" ] } }, "required": [ "provider_binding_id", "installation", "release_path", "entrypoint" ], "type": "object" }, "InstallationIdentity": { "additionalProperties": false, "description": "Identity claims derived from the retained scientific definition. They do not\nindependently attest the provider's installed software.", "properties": { "dataset_identities": { "items": { "type": "string" }, "type": "array" }, "model_identity": { "type": "string" }, "runtime_identity": { "type": "string" }, "wrapper_identity": { "type": "string" }, "wrapper_protocol_version": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "model_identity", "wrapper_identity", "runtime_identity", "wrapper_protocol_version", "dataset_identities" ], "type": "object" }, "InstallationSpec": { "additionalProperties": false, "properties": { "entrypoint": { "description": "Executable relative to release_path followed by fixed arguments.", "items": { "type": "string" }, "maxItems": 32, "minItems": 1, "type": "array" }, "environment": { "additionalProperties": { "type": "string" }, "maxProperties": 32, "type": "object" }, "release_path": { "description": "Absolute immutable release-specific path below an allowed installation root. Compute authorization and installation keys are resolved by registration.", "maxLength": 4096, "type": "string" }, "slurm_script": { "description": "Model-owned batch file relative to release_path; required for Slurm, omitted for process.", "maxLength": 4096, "minLength": 1, "type": [ "string", "null" ] } }, "required": [ "release_path", "entrypoint" ], "type": "object" }, "InvitationAcceptance": { "additionalProperties": false, "properties": { "token": { "maxLength": 43, "minLength": 43, "type": "string", "writeOnly": true } }, "required": [ "token" ], "type": "object" }, "InvitationCreate": { "description": "Exactly one non-null recipient is required; email invitations bind to an identity-provider-verified email.", "oneOf": [ { "additionalProperties": false, "properties": { "recipient_email": { "type": "null" }, "recipient_id": { "format": "uuid", "type": "string" } }, "required": [ "recipient_id" ], "type": "object" }, { "additionalProperties": false, "properties": { "recipient_email": { "format": "email", "maxLength": 320, "type": "string" }, "recipient_id": { "type": "null" } }, "required": [ "recipient_email" ], "type": "object" } ] }, "InvitationReceipt": { "properties": { "expires_at": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "model_id": { "type": "string" }, "token": { "type": "string" } }, "required": [ "id", "model_id", "token", "expires_at" ], "type": "object" }, "InvitationSummary": { "properties": { "accepted_at": { "type": [ "string", "null" ] }, "accepted_by": { "format": "uuid", "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "expires_at": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "model_id": { "type": "string" }, "recipient_email": { "type": [ "string", "null" ] }, "recipient_id": { "format": "uuid", "type": [ "string", "null" ] }, "status": { "type": "string" } }, "required": [ "id", "model_id", "recipient_id", "recipient_email", "expires_at", "accepted_by", "accepted_at", "created_at", "status" ], "type": "object" }, "LogArchiveIntent": { "additionalProperties": false, "properties": { "attempt_id": { "format": "uuid", "type": "string" }, "diagnostic": { "type": [ "string", "null" ] }, "finalized_at": { "type": [ "string", "null" ] }, "policy": { "$ref": "#/components/schemas/LogPolicy" } }, "required": [ "attempt_id", "policy" ], "type": "object" }, "LogArchiveManifest": { "additionalProperties": false, "properties": { "assignment_id": { "format": "uuid", "type": "string" }, "attempt_id": { "format": "uuid", "type": "string" }, "complete": { "type": "boolean" }, "launch_intent_id": { "format": "uuid", "type": "string" }, "sources": { "additionalProperties": { "$ref": "#/components/schemas/ArchiveSource" }, "propertyNames": { "pattern": "^(stdout|stderr|connector|slurm_batch|model\\.[a-z][a-z0-9_-]{0,63})$", "type": "string" }, "type": "object" }, "version": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "version", "assignment_id", "attempt_id", "launch_intent_id", "sources", "complete" ], "type": "object" }, "LogArchiveStatus": { "properties": { "artifact_id": { "format": "uuid", "type": [ "string", "null" ] }, "diagnostic": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "manifest": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LogArchiveManifest" } ] }, "state": { "$ref": "#/components/schemas/ArchiveState" } }, "required": [ "state" ], "type": "object" }, "LogBatchRequest": { "additionalProperties": false, "properties": { "attempt_id": { "format": "uuid", "type": "string" }, "byte_length": { "description": "Source bytes consumed by text, independent of replacement UTF-8 length.", "format": "int64", "maximum": 8192, "minimum": 0, "type": "integer" }, "gap": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LogGap" } ] }, "offset": { "description": "Start of text, after any omitted bytes, in this epoch.", "format": "int64", "minimum": 0, "type": "integer" }, "text": { "maxLength": 8192, "type": "string" } }, "required": [ "attempt_id", "offset", "byte_length", "text" ], "type": "object" }, "LogEntry": { "properties": { "assignment_id": { "format": "uuid", "type": "string" }, "byte_length": { "format": "int64", "type": "integer" }, "epoch": { "format": "int64", "type": "integer" }, "gap": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LogGap" } ] }, "offset": { "format": "int64", "type": "integer" }, "position": { "format": "int64", "type": "integer" }, "received_at": { "format": "date-time", "type": "string" }, "sequence": { "format": "int64", "type": "integer" }, "source": { "$ref": "#/components/schemas/LogSource" }, "source_reset": { "description": "True on the first batch of a replacement source epoch. Data may have\nbeen lost at this reset even when the omitted byte count is unknown.", "type": "boolean" }, "text": { "type": "string" } }, "required": [ "position", "assignment_id", "source", "epoch", "sequence", "offset", "byte_length", "text", "source_reset", "received_at" ], "type": "object" }, "LogFileDeclaration": { "additionalProperties": false, "properties": { "path": { "maxLength": 1024, "minLength": 1, "type": "string" } }, "required": [ "path" ], "type": "object" }, "LogGap": { "additionalProperties": false, "properties": { "bytes": { "description": "Null only for loss whose size cannot be established, in a new epoch.", "format": "int64", "type": [ "integer", "null" ] }, "reason": { "$ref": "#/components/schemas/LogGapReason" } }, "required": [ "reason" ], "type": "object" }, "LogGapReason": { "enum": [ "capture_truncated", "source_unavailable", "retention_discarded", "source_reset" ], "type": "string" }, "LogHistory": { "properties": { "items": { "items": { "$ref": "#/components/schemas/LogEntry" }, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] }, "resume_cursor": { "description": "Always present, including an empty page; suitable for SSE or polling.", "type": "string" }, "retention": { "$ref": "#/components/schemas/RetentionBoundary" } }, "required": [ "items", "resume_cursor", "retention" ], "type": "object" }, "LogPolicy": { "additionalProperties": false, "properties": { "archive_compressed_bytes": { "default": 52428800, "format": "int64", "minimum": 0, "type": "integer" }, "archive_enabled": { "default": false, "type": "boolean" }, "archive_publication_seconds": { "default": 86400, "format": "int64", "minimum": 0, "type": "integer" }, "archive_source_bytes": { "default": 16777216, "format": "int64", "minimum": 0, "type": "integer" }, "retained_segments": { "default": 16, "format": "int32", "minimum": 0, "type": "integer" }, "segment_bytes": { "default": 65536, "format": "int64", "minimum": 0, "type": "integer" } }, "type": "object" }, "LogReceipt": { "properties": { "assignment_id": { "format": "uuid", "type": "string" }, "epoch": { "format": "int64", "type": "integer" }, "position": { "format": "int64", "type": "integer" }, "received_at": { "format": "date-time", "type": "string" }, "sequence": { "format": "int64", "type": "integer" }, "source": { "$ref": "#/components/schemas/LogSource" } }, "required": [ "assignment_id", "source", "epoch", "sequence", "position", "received_at" ], "type": "object" }, "LogSource": { "pattern": "^(stdout|stderr|connector|slurm_batch|model\\.[a-z][a-z0-9_-]{0,63})$", "type": "string" }, "ManagedModel": { "properties": { "access_mode": { "$ref": "#/components/schemas/AccessMode" }, "can_manage": { "type": "boolean" }, "can_run": { "type": "boolean" }, "current_publication": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CurrentPublication" } ] }, "current_publication_id": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "generation": { "format": "int64", "type": "integer" }, "model_id": { "type": "string" }, "name": { "type": "string" }, "owner_id": { "format": "uuid", "type": "string" }, "visibility": { "$ref": "#/components/schemas/Visibility" } }, "required": [ "model_id", "name", "description", "owner_id", "generation", "access_mode", "visibility", "current_publication_id", "can_run", "can_manage", "current_publication" ], "type": "object" }, "ManagedRun": { "properties": { "created_at": { "type": "string" }, "created_by_user_id": { "format": "uuid", "type": "string" }, "model_id": { "type": "string" }, "publication_id": { "type": "string" }, "purpose": { "type": "string" }, "run_id": { "format": "uuid", "type": "string" }, "state": { "type": "string" } }, "required": [ "run_id", "model_id", "publication_id", "purpose", "created_by_user_id", "state", "created_at" ], "type": "object" }, "MeResponse": { "properties": { "credential_scopes": { "description": "Explicit credential bounds; resource memberships are checked separately.", "items": { "type": "string" }, "type": "array" }, "is_platform_admin": { "type": "boolean" }, "label": { "description": "Display label, which need not be unique.", "type": "string" }, "permissions": { "description": "Available user operations in stable order. Each request independently\nenforces model grants, creator ownership, state, and admission requirements.", "items": { "$ref": "#/components/schemas/UserPermission" }, "type": "array" }, "user_id": { "description": "Stable user identity; credential rotation does not change this ID.", "format": "uuid", "type": "string" } }, "required": [ "user_id", "label", "permissions", "credential_scopes", "is_platform_admin" ], "type": "object" }, "MemberPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/MemberView" }, "type": "array" }, "next_cursor": { "format": "int32", "minimum": 0, "type": [ "integer", "null" ] } }, "required": [ "items" ], "type": "object" }, "MemberSpec": { "additionalProperties": false, "properties": { "checksum_sha256": { "maxLength": 44, "minLength": 44, "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "type": "string" }, "media_type": { "type": "string" }, "path": { "type": "string" }, "scientific_metadata": {}, "size_bytes": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "path", "media_type", "scientific_metadata", "size_bytes", "checksum_sha256" ], "type": "object" }, "MemberView": { "properties": { "artifact_id": { "format": "uuid", "type": [ "string", "null" ] }, "available": { "type": "boolean" }, "index": { "format": "int32", "minimum": 0, "type": "integer" }, "member_id": { "format": "uuid", "type": "string" }, "spec": { "$ref": "#/components/schemas/MemberSpec" }, "version_id": { "type": [ "string", "null" ] } }, "required": [ "index", "member_id", "spec", "available" ], "type": "object" }, "MembershipChange": { "additionalProperties": false, "properties": { "expected_generation": { "format": "int64", "minimum": 1, "type": "integer" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "user_id", "expected_generation" ], "type": "object" }, "MembershipReceipt": { "properties": { "co_admin": { "type": "boolean" }, "generation": { "format": "int64", "type": "integer" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "user_id", "co_admin", "generation" ], "type": "object" }, "ModelCreate": { "additionalProperties": false, "properties": { "model": { "additionalProperties": false, "properties": { "description": { "maxLength": 16384, "type": "string" }, "id": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "id", "name", "description" ], "type": "object" } }, "required": [ "model" ], "type": "object" }, "ModelList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ModelSummary" }, "type": "array" }, "next_cursor": { "description": "Opaque continuation for this user and collection; null at the end.", "type": [ "string", "null" ] } }, "required": [ "items" ], "type": "object" }, "ModelSummary": { "description": "Editable catalog metadata. Discovery does not assert execution availability.", "properties": { "description": { "type": "string" }, "model_id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "model_id", "name", "description" ], "type": "object" }, "MultipartCompletion": { "additionalProperties": false, "properties": { "multipart": { "type": "boolean" } }, "required": [ "multipart" ], "type": "object" }, "MultipartSubmission": { "additionalProperties": { "$ref": "#/components/schemas/AttachmentBody" }, "description": "Named file properties vary by request; the request JSON maps those names to\nschema-declared inputs. File bodies are raw bytes, never JSON/base64 strings.", "properties": { "request": { "$ref": "#/components/schemas/RunSubmission" } }, "required": [ "request" ], "type": "object" }, "ObjectChecksum": { "description": "Full-object SHA-256, deliberately distinct from an ETag or multipart digest.", "properties": { "algorithm": { "$ref": "#/components/schemas/ChecksumAlgorithm" }, "checksum_type": { "$ref": "#/components/schemas/ChecksumType" }, "value": { "maxLength": 44, "minLength": 44, "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "type": "string" } }, "required": [ "algorithm", "checksum_type", "value" ], "type": "object" }, "ObservationFreshness": { "description": "Recency of confirmed run observations, independent of execution and connectivity.", "enum": [ "unknown", "fresh", "stale" ], "type": "string" }, "OperationalRun": { "properties": { "blocked_reason": { "type": [ "string", "null" ] }, "connector_id": { "type": "string" }, "context_id": { "type": "string" }, "created_at": { "type": "string" }, "execution_location": { "type": "string" }, "model_id": { "type": "string" }, "phase": { "type": [ "string", "null" ] }, "publication_id": { "type": "string" }, "run_id": { "format": "uuid", "type": "string" }, "state": { "type": "string" } }, "required": [ "run_id", "model_id", "publication_id", "context_id", "execution_location", "connector_id", "state", "phase", "created_at", "blocked_reason" ], "type": "object" }, "PartAuthorization": { "properties": { "checksum_sha256": { "type": "string" }, "part_number": { "format": "int32", "type": "integer" }, "request": { "$ref": "#/components/schemas/ScopedTransfer" }, "size_bytes": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "part_number", "size_bytes", "checksum_sha256", "request" ], "type": "object" }, "PartPage": { "properties": { "next_after": { "format": "int32", "type": [ "integer", "null" ] }, "parts": { "items": { "$ref": "#/components/schemas/PartView" }, "type": "array" } }, "required": [ "parts" ], "type": "object" }, "PartRequest": { "additionalProperties": false, "properties": { "checksum_sha256": { "type": "string" } }, "required": [ "checksum_sha256" ], "type": "object" }, "PartView": { "properties": { "checksum_sha256": { "type": "string" }, "etag": { "type": [ "string", "null" ] }, "part_number": { "format": "int32", "type": "integer" }, "size_bytes": { "format": "int64", "type": "integer" } }, "required": [ "part_number", "size_bytes", "checksum_sha256" ], "type": "object" }, "PendingPreflight": { "additionalProperties": false, "properties": { "connector_id": { "type": "string" }, "context_id": { "type": "string" }, "definition": { "$ref": "#/components/schemas/ExecutionContextDefinition" }, "ownership_generation": { "format": "int64", "type": "integer" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "request_id", "connector_id", "context_id", "definition", "ownership_generation" ], "type": "object" }, "PreflightAttempt": { "additionalProperties": false, "properties": { "expires_at": { "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "requested_at": { "type": "string" }, "state": { "$ref": "#/components/schemas/AttemptState" } }, "required": [ "request_id", "requested_at", "expires_at", "state" ], "type": "object" }, "PreflightRequest": { "additionalProperties": false, "properties": { "definition_hash": { "type": "string" }, "expected_ownership_generation": { "format": "int64", "type": "integer" }, "expected_previous_request_id": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "expected_ownership_generation", "definition_hash" ], "type": "object" }, "PreflightSubmission": { "additionalProperties": false, "properties": { "report": { "$ref": "#/components/schemas/HostPreflightReport" }, "session_id": { "format": "uuid", "type": "string" } }, "required": [ "session_id", "report" ], "type": "object" }, "PreflightSummary": { "properties": { "current_blocked": { "format": "int64", "type": "integer" }, "current_ready": { "format": "int64", "type": "integer" }, "pending": { "format": "int64", "type": "integer" }, "stale_or_unavailable": { "format": "int64", "type": "integer" } }, "required": [ "pending", "current_ready", "current_blocked", "stale_or_unavailable" ], "type": "object" }, "ProcessDriverConfig": { "additionalProperties": false, "properties": { "kind": { "enum": [ "process" ], "type": "string" }, "scratch": { "$ref": "#/components/schemas/ProcessScratchPolicy" } }, "required": [ "kind" ], "type": "object" }, "ProcessScratchPolicy": { "additionalProperties": false, "properties": { "cache": { "enum": [ "none", "per_run" ], "type": "string" }, "max_bytes": { "maximum": 18446744073709552000, "minimum": 1, "type": "integer" }, "max_depth": { "maximum": 64, "minimum": 1, "type": "integer" }, "max_entries": { "maximum": 1000000, "minimum": 1, "type": "integer" }, "scan_interval_ms": { "maximum": 60000, "minimum": 100, "type": "integer" }, "symlinks": { "enum": [ "forbid", "workspace_only" ], "type": "string" } }, "required": [ "max_bytes", "max_entries", "max_depth", "scan_interval_ms", "cache", "symlinks" ], "type": "object" }, "Progress": { "properties": { "confirmed_bytes": { "format": "int64", "minimum": 0, "type": "integer" }, "diagnostic": { "type": [ "string", "null" ] }, "part_count": { "format": "int32", "type": "integer" }, "part_size_bytes": { "format": "int64", "minimum": 0, "type": "integer" }, "phase": { "type": "string" } }, "required": [ "phase", "part_size_bytes", "part_count", "confirmed_bytes" ], "type": "object" }, "ProvenanceArtifact": { "description": "Immutable verified file evidence. Availability is deliberately separate: an\nexpired file does not rewrite the exact version used or produced by a run.", "properties": { "artifact_id": { "format": "uuid", "type": "string" }, "checksum": { "$ref": "#/components/schemas/UploadChecksum" }, "created_at": { "format": "date-time", "type": "string" }, "logical_name": { "type": "string" }, "media_type": { "type": "string" }, "name": { "description": "Declared input/output position, independent of the artifact logical name.", "type": "string" }, "producer": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ArtifactProducer", "description": "Null for user uploads; direct producer identity for model-to-model reuse.\nFollow the same authorized producer provenance route for further ancestry." } ] }, "scientific_metadata": {}, "size_bytes": { "format": "int64", "minimum": 0, "type": "integer" }, "storage_destination_id": { "type": "string" }, "verified_at": { "format": "date-time", "type": "string" }, "version_id": { "type": "string" } }, "required": [ "name", "artifact_id", "logical_name", "media_type", "scientific_metadata", "storage_destination_id", "version_id", "size_bytes", "checksum", "created_at", "verified_at" ], "type": "object" }, "ProvenanceCollection": { "properties": { "collection_id": { "format": "uuid", "type": "string" }, "manifest_digest": { "type": "string" }, "member_count": { "format": "int32", "minimum": 0, "type": "integer" }, "name": { "type": "string" }, "total_bytes": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "name", "collection_id", "manifest_digest", "member_count", "total_bytes" ], "type": "object" }, "ProvenanceRun": { "properties": { "cancelled_at": { "format": "date-time", "type": [ "string", "null" ] }, "contract_version": { "format": "int32", "minimum": 0, "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "created_by_user_id": { "format": "uuid", "type": "string" }, "effective_inputs": {}, "model_id": { "type": "string" }, "phase": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RunPhase" } ] }, "publication_delegation_id": { "format": "uuid", "type": [ "string", "null" ] }, "publication_id": { "type": "string" }, "purpose": { "$ref": "#/components/schemas/RunPurpose" }, "requested_inputs": {}, "run_id": { "format": "uuid", "type": "string" }, "state": { "$ref": "#/components/schemas/RunState" }, "storage_destination_id": { "type": [ "string", "null" ] } }, "required": [ "publication_id", "run_id", "created_by_user_id", "model_id", "contract_version", "requested_inputs", "effective_inputs", "state", "created_at" ], "type": "object" }, "PublicationActivation": { "additionalProperties": false, "properties": { "expected_current_publication_id": { "description": "Null or omitted for first publication; otherwise the previously observed current publication.", "type": [ "string", "null" ] }, "publication_delegation_id": { "description": "Exact named handoff; required when the activator is not the captured grant holder.", "format": "uuid", "type": [ "string", "null" ] } }, "type": "object" }, "PublicationActivationReceipt": { "properties": { "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status" ], "type": "object" }, "PublicationConfigurationRetention": { "properties": { "blockers": { "$ref": "#/components/schemas/PublicationRetirementBlockers" }, "requested_at": { "type": [ "string", "null" ] }, "retired_at": { "type": [ "string", "null" ] }, "retirement_blocked": { "type": "boolean" }, "state": { "type": "string" } }, "required": [ "state", "retirement_blocked", "blockers" ], "type": "object" }, "PublicationCreate": { "additionalProperties": false, "properties": { "context_id": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "definition": { "$ref": "#/components/schemas/ScientificDefinition" }, "descriptor": { "$ref": "#/components/schemas/InstallationSpec" }, "id": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" } }, "required": [ "id", "definition", "context_id", "descriptor" ], "type": "object" }, "PublicationDelegation": { "properties": { "created_at": { "type": "string" }, "created_by": { "format": "uuid", "type": "string" }, "expected_generation": { "format": "int64", "type": "integer" }, "grant_id": { "format": "uuid", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "publication_id": { "type": "string" }, "revocation_reason": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "id", "publication_id", "grant_id", "created_by", "user_id", "expected_generation", "created_at", "revoked_at", "revocation_reason" ], "type": "object" }, "PublicationDelegationCreate": { "additionalProperties": false, "properties": { "expected_generation": { "format": "int64", "minimum": 1, "type": "integer" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "user_id", "expected_generation" ], "type": "object" }, "PublicationDependency": { "properties": { "configuration_retention": { "$ref": "#/components/schemas/PublicationConfigurationRetention" }, "current": { "type": [ "boolean", "null" ] }, "grant_holder_user_id": { "format": "uuid", "type": "string" }, "grant_id": { "format": "uuid", "type": "string" }, "id": { "type": "string" }, "installation_revoked_at": { "type": [ "string", "null" ] }, "model_archived": { "type": "boolean" }, "model_id": { "type": "string" }, "model_owner_id": { "format": "uuid", "type": "string" }, "revoked_at": { "type": [ "string", "null" ] }, "status": { "type": "string" } }, "required": [ "id", "model_id", "model_owner_id", "grant_id", "grant_holder_user_id", "status", "current", "model_archived", "revoked_at", "installation_revoked_at", "configuration_retention" ], "type": "object" }, "PublicationDetail": { "properties": { "activation_availability": { "$ref": "#/components/schemas/PublicationReleaseAuthority" }, "admission_open": { "type": "boolean" }, "admission_updated_at": { "type": [ "string", "null" ] }, "configuration_retention": { "$ref": "#/components/schemas/PublicationConfigurationRetention" }, "context_id": { "type": "string" }, "created_at": { "type": "string" }, "definition": { "$ref": "#/components/schemas/ScientificDefinition" }, "descriptor": { "$ref": "#/components/schemas/InstallationDescriptor" }, "disclosure": { "type": "string" }, "execution_location": { "type": "string" }, "generation": { "format": "int64", "type": "integer" }, "grant_id": { "format": "uuid", "type": "string" }, "id": { "type": "string" }, "installation_revoked_at": { "type": [ "string", "null" ] }, "model_id": { "type": "string" }, "published_at": { "type": [ "string", "null" ] }, "release_authority": { "$ref": "#/components/schemas/PublicationReleaseAuthority" }, "revoked_at": { "type": [ "string", "null" ] }, "rollback_availability": { "$ref": "#/components/schemas/PublicationRollbackAvailability" }, "status": { "type": "string" }, "trial_availability": { "$ref": "#/components/schemas/Availability" }, "trial_evidence": { "$ref": "#/components/schemas/PublicationTrialEvidence" }, "validation_evidence": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicationValidationEvidence" } ] }, "validation_message": { "type": [ "string", "null" ] } }, "required": [ "trial_availability", "trial_evidence", "id", "admission_open", "admission_updated_at", "model_id", "context_id", "execution_location", "grant_id", "generation", "descriptor", "status", "validation_message", "disclosure", "revoked_at", "installation_revoked_at", "created_at", "published_at", "definition", "configuration_retention", "rollback_availability", "validation_evidence", "release_authority", "activation_availability" ], "type": "object" }, "PublicationProvenance": { "properties": { "compute_grant_id": { "format": "uuid", "type": "string" }, "context_id": { "type": "string" }, "disclosure": { "type": "string" }, "execution_location": { "type": "string" }, "generation": { "format": "int64", "type": "integer" }, "installation": { "$ref": "#/components/schemas/InstallationIdentity", "description": "Model-provider claims retained verbatim, not independent attestation." }, "publication_id": { "type": "string" }, "validation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicationValidation" } ] } }, "required": [ "publication_id", "context_id", "compute_grant_id", "generation", "execution_location", "disclosure", "installation" ], "type": "object" }, "PublicationRegistration": { "properties": { "generation": { "format": "int64", "type": [ "integer", "null" ] }, "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status" ], "type": "object" }, "PublicationReleaseAuthority": { "properties": { "available": { "type": "boolean" }, "can_delegate": { "type": "boolean" }, "grant_holder_user_id": { "format": "uuid", "type": "string" }, "publication_delegation_id": { "format": "uuid", "type": [ "string", "null" ] }, "unavailable_reason": { "type": [ "string", "null" ] } }, "required": [ "grant_holder_user_id", "publication_delegation_id", "can_delegate", "unavailable_reason", "available" ], "type": "object" }, "PublicationRetirement": { "additionalProperties": false, "properties": { "expected_generation": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "expected_generation" ], "type": "object" }, "PublicationRetirementBlockers": { "properties": { "pending_assignment_uploads": { "format": "int64", "minimum": 0, "type": "integer" }, "pending_delivery_assignments": { "format": "int64", "minimum": 0, "type": "integer" }, "pending_log_archives": { "format": "int64", "minimum": 0, "type": "integer" }, "queued_runs": { "format": "int64", "minimum": 0, "type": "integer" }, "running_runs": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "queued_runs", "running_runs", "pending_delivery_assignments", "pending_log_archives", "pending_assignment_uploads" ], "type": "object" }, "PublicationRetirementReceipt": { "properties": { "generation": { "format": "int64", "type": "integer" }, "model_id": { "type": "string" }, "publication_id": { "type": "string" }, "requested_at": { "type": "string" }, "state": { "type": "string" } }, "required": [ "publication_id", "model_id", "requested_at", "generation", "state" ], "type": "object" }, "PublicationRevocationReceipt": { "additionalProperties": false, "properties": { "affected_publication_ids": { "items": { "type": "string" }, "type": "array" }, "publication_id": { "type": "string" }, "revoked_at": { "format": "date-time", "type": "string" }, "scope": { "$ref": "#/components/schemas/RevocationScope" } }, "required": [ "scope", "affected_publication_ids", "publication_id", "revoked_at" ], "type": "object" }, "PublicationRollbackAvailability": { "properties": { "available": { "type": "boolean" }, "requires_revalidation": { "type": "boolean" }, "unavailable_reason": { "type": [ "string", "null" ] } }, "required": [ "available", "requires_revalidation" ], "type": "object" }, "PublicationSummary": { "properties": { "admission_open": { "type": "boolean" }, "configuration_retention": { "$ref": "#/components/schemas/PublicationConfigurationRetention" }, "context_id": { "type": "string" }, "created_at": { "type": "string" }, "definition": { "$ref": "#/components/schemas/ScientificDefinition" }, "descriptor": { "$ref": "#/components/schemas/InstallationDescriptor" }, "disclosure": { "type": "string" }, "execution_location": { "type": "string" }, "generation": { "format": "int64", "type": "integer" }, "grant_id": { "format": "uuid", "type": "string" }, "id": { "type": "string" }, "installation_revoked_at": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "rollback_availability": { "$ref": "#/components/schemas/PublicationRollbackAvailability" }, "status": { "type": "string" }, "validation_message": { "type": [ "string", "null" ] } }, "required": [ "id", "definition", "admission_open", "context_id", "grant_id", "generation", "descriptor", "status", "validation_message", "disclosure", "execution_location", "revoked_at", "installation_revoked_at", "created_at", "published_at", "configuration_retention", "rollback_availability" ], "type": "object" }, "PublicationTrialCounts": { "properties": { "cancelled": { "format": "int64", "minimum": 0, "type": "integer" }, "failed": { "format": "int64", "minimum": 0, "type": "integer" }, "queued": { "format": "int64", "minimum": 0, "type": "integer" }, "running": { "format": "int64", "minimum": 0, "type": "integer" }, "succeeded": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "object" }, "PublicationTrialEvidence": { "description": "Bounded management evidence; scientific results remain on authorized run routes.", "examples": [ { "counts": { "cancelled": 0, "failed": 0, "queued": 0, "running": 0, "succeeded": 1 }, "latest_run": { "created_at": "2026-11-02T10:00:00Z", "publication_id": "scalar-double-r1", "purpose": "candidate_trial", "run_id": "00000000-0000-4000-8000-000000000014", "state": "succeeded" }, "latest_succeeded_run": { "created_at": "2026-11-02T10:00:00Z", "publication_id": "scalar-double-r1", "purpose": "candidate_trial", "run_id": "00000000-0000-4000-8000-000000000014", "state": "succeeded" } }, { "counts": { "cancelled": 0, "failed": 0, "queued": 0, "running": 0, "succeeded": 0 }, "latest_run": null, "latest_succeeded_run": null } ], "properties": { "counts": { "$ref": "#/components/schemas/PublicationTrialCounts" }, "latest_run": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicationTrialRun" } ] }, "latest_succeeded_run": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicationTrialRun" } ] } }, "required": [ "counts", "latest_run", "latest_succeeded_run" ], "type": "object" }, "PublicationTrialPurpose": { "enum": [ "candidate_trial" ], "type": "string" }, "PublicationTrialRun": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "publication_id": { "type": "string" }, "purpose": { "$ref": "#/components/schemas/PublicationTrialPurpose" }, "run_id": { "format": "uuid", "type": "string" }, "state": { "$ref": "#/components/schemas/RunState" } }, "required": [ "run_id", "publication_id", "purpose", "state", "created_at" ], "type": "object" }, "PublicationValidation": { "properties": { "authority": { "description": "Always `connector_observed`; Enumeray itself did not inspect model files.", "type": "string" }, "connector_id": { "type": "string" }, "generation": { "format": "int64", "type": "integer" }, "observed_at": { "format": "date-time", "type": "string" }, "verified_digests": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" } }, "required": [ "authority", "connector_id", "generation", "verified_digests", "observed_at" ], "type": "object" }, "PublicationValidationAuthority": { "enum": [ "connector_observed" ], "type": "string" }, "PublicationValidationEvidence": { "examples": [ { "authority": "connector_observed", "observed_at": "2026-11-02T10:00:00Z", "verified_digests": { "wrapper.py": "13308b745dcad7f83e4e23e3d47362d8ba4ee9f7d883e688463c5782bf840b4c" } } ], "properties": { "authority": { "$ref": "#/components/schemas/PublicationValidationAuthority" }, "observed_at": { "format": "date-time", "type": "string" }, "verified_digests": { "additionalProperties": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "type": "object" } }, "required": [ "authority", "verified_digests", "observed_at" ], "type": "object" }, "QueueBlockReason": { "description": "A queued run cannot currently be assigned through an approved execution path.\n\nCapacity exhaustion and temporary disconnection are ordinary queue waiting.\nClosing new admission does not block already accepted runs.", "enum": [ "publication_revoked", "installation_revoked", "no_approved_execution_path", "model_access_revoked", "compute_access_revoked", "compute_unavailable", "connector_maintenance", "context_cutover" ], "type": "string" }, "ReplacementAction": { "properties": { "action": { "type": "string" }, "blocking_publications": { "format": "int64", "type": [ "integer", "null" ] }, "local_cleanup_state": { "type": [ "string", "null" ] }, "role": { "type": "string" } }, "required": [ "role", "action" ], "type": "object" }, "ReplacementContext": { "properties": { "connection": { "type": "string" }, "connector_id": { "type": "string" }, "driver": { "type": "string" }, "generation": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/ContextMetadata" }, "state": { "$ref": "#/components/schemas/ContextLifecycleState" } }, "required": [ "id", "connector_id", "state", "generation", "driver", "connection", "metadata" ], "type": "object" }, "ReportSource": { "enum": [ "local", "connector" ], "type": "string" }, "ReportValidity": { "enum": [ "current", "stale", "unavailable" ], "type": "string" }, "ResolutionSummary": { "additionalProperties": false, "description": "Safe reconciliation marker. No operator identity, notes, or process IDs.", "properties": { "assignment_id": { "format": "uuid", "type": "string" }, "attempt_id": { "format": "uuid", "type": "string" }, "execution_status": { "$ref": "#/components/schemas/ExecutionStatus" }, "resolved_at": { "format": "date-time", "type": "string" } }, "required": [ "assignment_id", "attempt_id", "execution_status", "resolved_at" ], "type": "object" }, "ResourceMembers": { "properties": { "co_admins": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "generation": { "format": "int64", "type": "integer" }, "owner_id": { "format": "uuid", "type": "string" } }, "required": [ "owner_id", "generation", "co_admins" ], "type": "object" }, "ResponsibleRole": { "enum": [ "connector_owner", "host_administrator", "site_operator" ], "type": "string" }, "ResultFailure": { "additionalProperties": false, "description": "Private bounded failure details, never included in diagnostics or tracing.", "properties": { "code": { "maxLength": 64, "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$", "type": "string" }, "message": { "description": "At most 2048 UTF-8 bytes. Only tab and newline control characters allowed.", "maxLength": 2048, "minLength": 1, "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "ResultOutcome": { "enum": [ "succeeded", "failed", "cancelled" ], "type": "string" }, "ResultReceipt": { "description": "Original committed acknowledgement, independent of later inspection time.", "properties": { "assignment_id": { "format": "uuid", "type": "string" }, "attempt_id": { "format": "uuid", "type": "string" }, "completed_at": { "format": "date-time", "type": "string" }, "outcome": { "$ref": "#/components/schemas/ResultOutcome" }, "provider_cleanup_acknowledged": { "description": "True only after this result and every file pin have committed. It permits\nremoval of provider work files, never deletion of API-retained artifacts.\nHistorical receipts and operator resolutions carry no cleanup authority.", "type": "boolean" }, "run_id": { "format": "uuid", "type": "string" } }, "required": [ "assignment_id", "run_id", "attempt_id", "outcome", "completed_at" ], "type": "object" }, "ResultRequest": { "additionalProperties": false, "properties": { "attempt_id": { "format": "uuid", "type": "string" }, "collections": { "additionalProperties": { "$ref": "#/components/schemas/CollectionReference" }, "propertyNames": { "type": "string" }, "type": "object" }, "execution_terminated": { "description": "Required true: execution has definitely stopped (or never started).\nLost contact or an uncertain submission acknowledgement cannot assert this.", "type": "boolean" }, "failure": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResultFailure" } ] }, "files": { "additionalProperties": { "$ref": "#/components/schemas/ArtifactReference" }, "description": "Declared file names mapped to {artifact_id}, matching outputs exactly.\nEach artifact must be verified, ready and produced by this assignment.", "propertyNames": { "type": "string" }, "type": "object" }, "optional_output_failures": { "additionalProperties": { "$ref": "#/components/schemas/ResultFailure" }, "propertyNames": { "type": "string" }, "type": "object" }, "outcome": { "$ref": "#/components/schemas/ResultOutcome" }, "outputs": { "description": "Schema-valid output values, including declared file artifact references." } }, "required": [ "attempt_id", "outcome", "execution_terminated", "outputs", "files", "optional_output_failures" ], "type": "object" }, "RetentionBoundary": { "properties": { "earliest_position": { "format": "int64", "type": [ "integer", "null" ] }, "latest_position": { "format": "int64", "type": "integer" }, "payload_max_age_seconds": { "description": "Null for immutable observation evidence, which has no expiry policy.", "format": "int64", "type": [ "integer", "null" ] }, "payload_max_entries": { "format": "int64", "type": [ "integer", "null" ] }, "recovery_cursor": { "description": "Resume at the earliest retained entry. Replacing an expired cursor with\nthis acknowledges the missing prefix; clients should display that gap.", "type": "string" } }, "required": [ "latest_position", "recovery_cursor" ], "type": "object" }, "RevocationScope": { "enum": [ "publication", "installation" ], "type": "string" }, "RevokedGrant": { "properties": { "id": { "format": "uuid", "type": "string" }, "revoked": { "type": "boolean" } }, "required": [ "id", "revoked" ], "type": "object" }, "RunDependency": { "properties": { "blocked_reason": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "model_id": { "type": "string" }, "phase": { "type": [ "string", "null" ] }, "publication_id": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "model_id", "publication_id", "state", "phase", "blocked_reason" ], "type": "object" }, "RunDetail": { "allOf": [ { "$ref": "#/components/schemas/RunSummary" }, { "properties": { "cancellation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CancellationReceipt", "description": "Durable user intent, distinct from current execution authorization." } ] }, "contract_version": { "format": "int32", "minimum": 0, "type": "integer" }, "created_by_user_id": { "format": "uuid", "type": "string" }, "disclosure": { "type": "string" }, "effective_inputs": {}, "execution_control": { "$ref": "#/components/schemas/ExecutionControl", "description": "Current authorization and recorded execution progress. Cancellation stays\npending until backend evidence establishes a terminal outcome." }, "publication_delegation_id": { "format": "uuid", "type": [ "string", "null" ] }, "requested_inputs": {}, "resolution": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResolutionSummary", "description": "Safe operator-resolution marker; private evidence and actor are omitted." } ] }, "result": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RunResult", "description": "Durable result for the submitter and current model owners/co-admins." } ] }, "storage_destination_id": { "description": "Absent on pre-storage work and scalar-only installations without a default.", "type": [ "string", "null" ] } }, "required": [ "execution_control", "created_by_user_id", "contract_version", "requested_inputs", "effective_inputs", "disclosure" ], "type": "object" } ], "description": "Current state alongside the original immutable acceptance facts." }, "RunList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/RunSummary" }, "type": "array" }, "next_cursor": { "description": "Opaque continuation. Repeat the same filters; the page size may change.", "type": [ "string", "null" ] } }, "required": [ "items" ], "type": "object" }, "RunPhase": { "description": "Monotonic progress within an assignment, not proof that an outcome is final.", "enum": [ "preparing", "waiting_for_backend", "executing", "collecting_results", "uploading_results" ], "type": "string" }, "RunProvenance": { "description": "Versioned JSON document; the download endpoint serializes this same document.\nStable ordering and the absence of an inspection timestamp make unchanged\nevidence byte-for-byte reproducible. In-progress runs accumulate more facts.", "properties": { "cancellation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CancellationReceipt" } ] }, "definition": { "$ref": "#/components/schemas/ScientificDefinition", "description": "Immutable registered scientific contract, including schemas and examples.\nIdentity labels are provider claims, not independent software attestation." }, "execution": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExecutionProvenance" } ] }, "format_version": { "format": "int32", "minimum": 0, "type": "integer" }, "input_artifacts": { "description": "Accepted file dependencies, ordered by declared input name.", "items": { "$ref": "#/components/schemas/ProvenanceArtifact" }, "type": "array" }, "input_collections": { "items": { "$ref": "#/components/schemas/ProvenanceCollection" }, "type": "array" }, "output_artifacts": { "description": "Verified files included in the committed result, ordered by output name.\nEmpty until finalization. Pending uploads are not execution results.", "items": { "$ref": "#/components/schemas/ProvenanceArtifact" }, "type": "array" }, "output_collections": { "items": { "$ref": "#/components/schemas/ProvenanceCollection" }, "type": "array" }, "publication": { "$ref": "#/components/schemas/PublicationProvenance", "description": "Immutable publication facts and separately attributed connector observation." }, "resolution": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResolutionSummary", "description": "Explicit operator outcome, without private operator evidence or identity." } ] }, "result": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RunResult" } ] }, "run": { "$ref": "#/components/schemas/ProvenanceRun" } }, "required": [ "format_version", "publication", "run", "definition", "input_artifacts", "output_artifacts" ], "type": "object" }, "RunPurpose": { "description": "Immutable submission intent. Candidate trials retain author/compute authority checks.", "enum": [ "standard", "candidate_trial" ], "type": "string" }, "RunResult": { "description": "Creator-private result and file manifest; also visible to the owning connector.", "properties": { "collections": { "additionalProperties": { "$ref": "#/components/schemas/CollectionReference" }, "propertyNames": { "type": "string" }, "type": "object" }, "failure": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResultFailure" } ] }, "files": { "additionalProperties": { "$ref": "#/components/schemas/ArtifactReference" }, "propertyNames": { "type": "string" }, "type": "object" }, "optional_output_failures": { "additionalProperties": { "$ref": "#/components/schemas/ResultFailure" }, "propertyNames": { "type": "string" }, "type": "object" }, "outputs": {}, "receipt": { "$ref": "#/components/schemas/ResultReceipt" } }, "required": [ "receipt", "outputs", "files", "optional_output_failures" ], "type": "object" }, "RunState": { "description": "Public execution state. Delegated preparation and collection are `running`.", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "RunSubmission": { "additionalProperties": false, "description": "Fully specified inputs for one exact publication; ownership comes from authentication.", "properties": { "expected_publication_id": { "description": "Exact publication: current-publication precondition for standard runs, explicit candidate for trials.", "type": "string" }, "inputs": { "description": "Required JSON value, including null when allowed by the publication schema.\nJSON Schema default annotations do not populate omitted inputs." }, "model_id": { "description": "Stable catalog model identity.", "type": "string" }, "publication_delegation_id": { "format": "uuid", "type": [ "string", "null" ] }, "purpose": { "$ref": "#/components/schemas/RunPurpose" } }, "required": [ "model_id", "expected_publication_id", "inputs" ], "type": "object" }, "RunSummary": { "description": "Small history entries exclude inputs and service-wide queue information.", "properties": { "blocked_reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/QueueBlockReason", "description": "A current eligibility diagnostic, not a promise that a claim will succeed." } ] }, "cancelled_at": { "format": "date-time", "type": [ "string", "null" ] }, "context_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "execution_location": { "type": "string" }, "last_observed_at": { "description": "API receipt time of the latest qualifying execution observation.", "format": "date-time", "type": [ "string", "null" ] }, "model_id": { "type": "string" }, "observation_freshness": { "$ref": "#/components/schemas/ObservationFreshness", "description": "API confirmation age: fresh below 60 seconds, stale at or above 60 seconds.\nMissing or future confirmation times are unknown." }, "phase": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RunPhase", "description": "Null until an assignment exists. Queued and terminal runs have no phase." } ] }, "publication_id": { "description": "Immutable publication captured at acceptance.", "type": "string" }, "purpose": { "$ref": "#/components/schemas/RunPurpose" }, "run_id": { "format": "uuid", "type": "string" }, "state": { "$ref": "#/components/schemas/RunState" } }, "required": [ "publication_id", "run_id", "model_id", "context_id", "execution_location", "state", "observation_freshness", "created_at" ], "type": "object" }, "ScientificDefinition": { "additionalProperties": false, "description": "Pinned identities and scientific schemas checked during registration.\n\nContract validation checks schemas and examples, not scientific correctness.\nRegistration does not activate a publication or verify the claimed identities.", "properties": { "contract_version": { "description": "Enumeray's interpretation of schema restrictions and input/output values.\nThis is independent of the wrapper protocol and JSON Schema dialect.", "format": "int32", "minimum": 0, "type": "integer" }, "dataset_identities": { "items": { "type": "string" }, "type": "array" }, "examples": { "items": { "$ref": "#/components/schemas/ScientificExample" }, "type": "array" }, "input_schema": {}, "log_files": { "additionalProperties": { "$ref": "#/components/schemas/LogFileDeclaration" }, "description": "Up to eight optional diagnostics, keyed by [a-z][a-z0-9_-]{0,63}.\nPaths are confined to the run workspace; diagnostics are independent of results.", "propertyNames": { "type": "string" }, "type": "object" }, "model_identity": { "type": "string" }, "output_schema": {}, "runtime_identity": { "type": "string" }, "wrapper_identity": { "type": "string" }, "wrapper_protocol_version": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "contract_version", "model_identity", "wrapper_identity", "runtime_identity", "wrapper_protocol_version", "dataset_identities", "input_schema", "output_schema", "examples" ], "type": "object" }, "ScientificExample": { "additionalProperties": false, "description": "A named example validated at registration and preserved for discovery.", "properties": { "inputs": {}, "name": { "type": "string" }, "outputs": {} }, "required": [ "name", "inputs" ], "type": "object" }, "ScopedTransfer": { "description": "Send exactly this method, URL, and headers. Contains temporary authorization;\nserialize only for the authorized transfer recipient and never log it.", "properties": { "expires_in_seconds": { "format": "int64", "minimum": 0, "type": "integer" }, "headers": { "items": { "items": false, "prefixItems": [ { "type": "string" }, { "type": "string" } ], "type": "array" }, "type": "array" }, "method": { "type": "string" }, "url": { "type": "string" } }, "required": [ "method", "url", "headers", "expires_in_seconds" ], "type": "object" }, "SessionReceipt": { "properties": { "connector_id": { "type": "string" }, "journal_id": { "format": "uuid", "type": "string" }, "session_id": { "format": "uuid", "type": "string" } }, "required": [ "connector_id", "journal_id", "session_id" ], "type": "object" }, "SessionRecoveryRequest": { "additionalProperties": false, "description": "Persist this exact transition before sending it. The stopped-process\nassertion is a prerequisite established by the caller, never a heartbeat or\nlease inference, and does not assert that any backend execution has stopped.", "properties": { "journal_id": { "format": "uuid", "type": "string" }, "previous_session_id": { "format": "uuid", "type": "string" }, "prior_process_stopped": { "type": "boolean" }, "session_id": { "format": "uuid", "type": "string" } }, "required": [ "journal_id", "previous_session_id", "session_id", "prior_process_stopped" ], "type": "object" }, "SessionRequest": { "additionalProperties": false, "properties": { "journal_id": { "format": "uuid", "type": "string" }, "session_id": { "format": "uuid", "type": "string" } }, "required": [ "journal_id", "session_id" ], "type": "object" }, "SetupIssue": { "properties": { "check": { "type": [ "string", "null" ] }, "code": { "type": "string" }, "correction": { "type": "string" }, "outcome": { "$ref": "#/components/schemas/CheckOutcome" }, "responsible_role": { "$ref": "#/components/schemas/ResponsibleRole" } }, "required": [ "code", "outcome", "responsible_role", "correction" ], "type": "object" }, "SlurmDriverConfig": { "additionalProperties": false, "properties": { "kind": { "enum": [ "slurm" ], "type": "string" }, "worker_path": { "type": "string" } }, "required": [ "kind", "worker_path" ], "type": "object" }, "SourceIdentity": { "additionalProperties": false, "description": "Exact build inputs; dirty builds retain an immutable content fingerprint.", "properties": { "clean": { "type": "boolean" }, "content_sha256": { "type": "string" }, "lockfile_sha256": { "type": [ "string", "null" ] }, "repository": { "type": "string" }, "revision": { "type": [ "string", "null" ] }, "tree": { "type": [ "string", "null" ] } }, "required": [ "repository", "clean", "content_sha256" ], "type": "object" }, "SshConnectionConfig": { "additionalProperties": false, "properties": { "credential_reference": { "type": "string" }, "host": { "type": "string" }, "kind": { "enum": [ "ssh" ], "type": "string" }, "port": { "maximum": 65535, "minimum": 1, "type": "integer" }, "runner_path": { "type": "string" }, "user": { "type": "string" } }, "required": [ "kind", "host", "user", "port", "credential_reference", "runner_path" ], "type": "object" }, "SubmissionAvailability": { "properties": { "admission_open": { "type": "boolean" }, "execution_destination": { "$ref": "#/components/schemas/ExecutionDestination" }, "has_approved_execution_path": { "type": "boolean" }, "unavailable_reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SubmissionUnavailableReason" } ] } }, "required": [ "admission_open", "has_approved_execution_path", "unavailable_reason", "execution_destination" ], "type": "object" }, "SubmissionReceipt": { "additionalProperties": false, "description": "The original creation receipt, replayed even after the run progresses.\nCurrent run state is a separate inspection concern.", "properties": { "created_at": { "description": "Acceptance time in UTC, formatted as RFC 3339.", "format": "date-time", "type": "string" }, "model_id": { "type": "string" }, "publication_delegation_id": { "format": "uuid", "type": [ "string", "null" ] }, "publication_id": { "type": "string" }, "purpose": { "$ref": "#/components/schemas/RunPurpose" }, "run_id": { "format": "uuid", "type": "string" }, "state": { "description": "Initial accepted state, always `queued`; replay is not a fresh observation.", "example": "queued", "type": "string" } }, "required": [ "publication_id", "run_id", "model_id", "state", "created_at" ], "type": "object" }, "SubmissionUnavailableReason": { "enum": [ "publication_revoked", "installation_revoked", "admission_closed", "no_approved_execution_path", "connector_maintenance", "context_not_active" ], "type": "string" }, "TokenInfo": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "revoked_at": { "format": "date-time", "type": [ "string", "null" ] }, "scopes": { "description": "Current retained scopes, including '*' for operator-issued credentials. Delegated issuance never accepts '*'.", "items": { "enum": [ "me:read", "models:read", "models:manage", "runs:create", "runs:read", "runs:cancel", "uploads:create", "uploads:read", "uploads:complete", "artifacts:read", "artifacts:download", "connectors:read", "connectors:manage", "access:manage", "tokens:manage", "audit:read", "service:read", "service:manage", "*" ], "type": "string" }, "maxItems": 32, "minItems": 1, "type": "array" } }, "required": [ "id", "name", "scopes", "created_at", "expires_at", "revoked_at" ], "type": "object" }, "TokenIssued": { "description": "Delivered exactly once. Store privately and never print to diagnostic logs.", "properties": { "expires_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "scopes": { "items": { "enum": [ "me:read", "models:read", "models:manage", "runs:create", "runs:read", "runs:cancel", "uploads:create", "uploads:read", "uploads:complete", "artifacts:read", "artifacts:download", "connectors:read", "connectors:manage", "access:manage", "tokens:manage", "audit:read", "service:read", "service:manage" ], "type": "string" }, "maxItems": 18, "minItems": 1, "type": "array" }, "token": { "type": "string" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "id", "user_id", "token", "expires_at", "scopes" ], "type": "object" }, "TokenPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TokenInfo" }, "type": "array" }, "next_cursor": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ], "type": "object" }, "TransferAcceptance": { "description": "Scoped clients send both non-null fields to guard the resource they intend to accept. A truly empty body or empty JSON object retains global acceptance for older clients. Every nonempty body requires a JSON content type. Guards are checked on exact retries too.", "oneOf": [ { "additionalProperties": false, "type": "object" }, { "additionalProperties": false, "properties": { "resource_id": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "resource_kind": { "enum": [ "model", "connector" ], "type": "string" } }, "required": [ "resource_kind", "resource_id" ], "type": "object" } ] }, "TransferAcceptanceReceipt": { "properties": { "accepted": { "type": "boolean" }, "generation": { "format": "int64", "type": [ "integer", "null" ] }, "id": { "format": "uuid", "type": "string" } }, "required": [ "id", "accepted" ], "type": "object" }, "TransferCreate": { "additionalProperties": false, "properties": { "expected_generation": { "format": "int64", "minimum": 1, "type": "integer" }, "to_user_id": { "format": "uuid", "type": "string" } }, "required": [ "to_user_id", "expected_generation" ], "type": "object" }, "TransferProposalReceipt": { "properties": { "id": { "format": "uuid", "type": "string" }, "to_user_id": { "format": "uuid", "type": "string" } }, "required": [ "id", "to_user_id" ], "type": "object" }, "UploadChecksum": { "additionalProperties": false, "properties": { "algorithm": { "$ref": "#/components/schemas/ChecksumAlgorithm", "description": "Only sha256 is supported." }, "checksum_type": { "$ref": "#/components/schemas/ChecksumType", "description": "Only full_object is supported; multipart checksums are not accepted." }, "value": { "description": "Canonical base64 of the 32-byte SHA-256 digest.", "maxLength": 44, "minLength": 44, "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "type": "string" } }, "required": [ "algorithm", "checksum_type", "value" ], "type": "object" }, "UploadCompletionReceipt": { "additionalProperties": false, "description": "Immutable publication acknowledgement, not a live storage availability probe.", "properties": { "artifact_id": { "format": "uuid", "type": "string" }, "checksum": { "$ref": "#/components/schemas/UploadChecksum" }, "completed_at": { "format": "date-time", "type": "string" }, "size_bytes": { "format": "int64", "minimum": 0, "type": "integer" }, "upload_id": { "format": "uuid", "type": "string" }, "version_id": { "type": "string" } }, "required": [ "upload_id", "artifact_id", "version_id", "size_bytes", "checksum", "completed_at" ], "type": "object" }, "UploadCompletionRequest": { "additionalProperties": false, "properties": { "version_id": { "description": "Exact non-null x-amz-version-id returned by storage. Retain it for retries.", "maxLength": 1024, "minLength": 1, "type": "string" } }, "required": [ "version_id" ], "type": "object" }, "UploadReceipt": { "additionalProperties": false, "description": "Immutable creation receipt. Kept independently of renewable transfer secrets\nand current state so the same user/key continues to identify the same upload.", "properties": { "artifact_id": { "description": "Reserved identity. Readiness requires a separate successful completion.", "format": "uuid", "type": "string" }, "checksum": { "$ref": "#/components/schemas/UploadChecksum" }, "created_at": { "format": "date-time", "type": "string" }, "expected_size_bytes": { "format": "int64", "minimum": 0, "type": "integer" }, "expires_at": { "format": "date-time", "type": "string" }, "logical_name": { "type": "string" }, "media_type": { "type": "string" }, "scientific_metadata": {}, "storage_destination_id": { "type": "string" }, "upload_id": { "format": "uuid", "type": "string" } }, "required": [ "upload_id", "artifact_id", "storage_destination_id", "logical_name", "media_type", "scientific_metadata", "expected_size_bytes", "checksum", "created_at", "expires_at" ], "type": "object" }, "UploadRequest": { "additionalProperties": false, "properties": { "checksum": { "$ref": "#/components/schemas/UploadChecksum" }, "expected_size_bytes": { "format": "int64", "maximum": 53687091200000, "minimum": 0, "type": "integer" }, "logical_name": { "type": "string" }, "media_type": { "type": "string" }, "scientific_metadata": {} }, "required": [ "logical_name", "media_type", "scientific_metadata", "expected_size_bytes", "checksum" ], "type": "object" }, "UploadState": { "enum": [ "pending", "expired", "completed" ], "type": "string" }, "UploadTransfer": { "oneOf": [ { "properties": { "expires_at": { "format": "date-time", "type": "string" }, "request": { "$ref": "#/components/schemas/ScopedTransfer" }, "status": { "enum": [ "available" ], "type": "string" } }, "required": [ "expires_at", "request", "status" ], "type": "object" }, { "description": "The reservation is durable. Retry its status resource to obtain authority.", "properties": { "status": { "enum": [ "unavailable" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, { "properties": { "progress": { "$ref": "#/components/schemas/Progress" }, "status": { "enum": [ "multipart" ], "type": "string" } }, "required": [ "progress", "status" ], "type": "object" }, { "properties": { "status": { "enum": [ "expired" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, { "description": "Publication succeeded; this service issues no further PUT instructions.", "properties": { "status": { "enum": [ "completed" ], "type": "string" } }, "required": [ "status" ], "type": "object" } ] }, "UploadView": { "properties": { "completion": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UploadCompletionReceipt" } ] }, "reservation": { "$ref": "#/components/schemas/UploadReceipt" }, "state": { "$ref": "#/components/schemas/UploadState" }, "transfer": { "$ref": "#/components/schemas/UploadTransfer" } }, "required": [ "reservation", "state", "transfer" ], "type": "object" }, "UserPermission": { "description": "User operations currently available to every authenticated user.\n\nThese describe API functionality; each request still enforces resource access\nand operation requirements. They confer no roles, token scopes, model grants,\nconnector access, or operator administration.", "enum": [ "me:read", "models:read", "runs:create", "runs:read", "runs:cancel", "uploads:create", "uploads:read", "uploads:complete", "artifacts:read", "artifacts:download", "models:manage", "connectors:read", "connectors:manage", "access:manage", "tokens:manage", "audit:read", "service:read", "service:manage" ], "type": "string" }, "ValidationDetails": { "description": "Safe, bounded guidance for inputs that do not satisfy a publication schema.", "properties": { "truncated": { "description": "More violations exist than fit in this response.", "type": "boolean" }, "violations": { "description": "At most eight violations, in validator traversal order.", "items": { "$ref": "#/components/schemas/InputViolation" }, "maxItems": 8, "type": "array" } }, "required": [ "violations", "truncated" ], "type": "object" }, "Visibility": { "enum": [ "listed", "unlisted" ], "type": "string" } }, "securitySchemes": { "connector_bearer": { "scheme": "bearer", "type": "http" }, "user_bearer": { "scheme": "bearer", "type": "http" } } }, "info": { "description": "Implemented HTTP endpoints. Every application response includes a fresh, server-generated x-request-id. Unknown paths return 404; unsupported methods return 405 with Allow. Where GET is supported, HEAD returns the GET response headers without a body.", "title": "Enumeray API", "version": "0.1.0-alpha.1" }, "openapi": "3.1.0", "paths": { "/api/v1/artifacts/{artifact_id}": { "get": { "description": "Inspect immutable artifact metadata and current availability.\n\n**Credential scopes:** `artifacts:read`\n\n**Resource authority:** Artifact creator, or current administrator of a run that produced or accepted the exact artifact dependency. Unrelated standalone uploads remain private.\n\n**Retry:** Repeat GET using the same resource identity; each request rechecks current credential and resource authority.\n\n**Guards:** Knowing an artifact UUID grants no authority.\n\n**Retain:** Artifact UUID and published version/size/SHA-256; never retain capability URLs.\n\n**Specific failures:** 403 insufficient_scope; 404 not_found: missing or unauthorized artifact; 503 artifact_unavailable\n\n**Next action:** Use content only when ready; keep immutable identities. [Worked workflow](/reference/http-workflows/)", "operationId": "get_artifact", "parameters": [ { "description": "Artifact identity readable by its creator or a current administrator of an accepting/producing run.", "in": "path", "name": "artifact_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactDetail" } } }, "description": "Immutable metadata, current availability and optional verified content evidence. No storage keys or temporary URLs.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Query parameters are not accepted.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active user credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid, unknown or unauthorized artifact; unrelated standalone uploads remain private.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Artifact records unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Artifacts" ], "x-enumeray-contract": { "errors": [ "403 insufficient_scope", "404 not_found: missing or unauthorized artifact", "503 artifact_unavailable" ], "guards": "Knowing an artifact UUID grants no authority.", "method": "get", "next_action": "Use content only when ready; keep immutable identities.", "path": "/api/v1/artifacts/{artifact_id}", "purpose": "Inspect immutable artifact metadata and current availability.", "retained": "Artifact UUID and published version/size/SHA-256; never retain capability URLs.", "retry": "Repeat GET using the same resource identity; each request rechecks current credential and resource authority.", "roles": "Artifact creator, or current administrator of a run that produced or accepted the exact artifact dependency. Unrelated standalone uploads remain private.", "scopes": [ "artifacts:read" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/artifacts/{artifact_id}/content": { "get": { "description": "Authorize an exact-version five-minute object-storage download.\n\n**Credential scopes:** `artifacts:download`\n\n**Resource authority:** Artifact creator, or current administrator of a run that produced or accepted the exact artifact dependency. Unrelated standalone uploads remain private.\n\n**Retry:** Repeat GET using the same resource identity; each request rechecks current credential and resource authority.\n\n**Guards:** For content, exact published version is verified and credential, membership and availability are rechecked before issuing a 303. Follow Location in a separate storage request without API bearer headers.\n\n**Retain:** Artifact UUID and published version/size/SHA-256; never retain capability URLs.\n\n**Specific failures:** 403 insufficient_scope; 404 not_found; 409 artifact_not_ready; 410 artifact_gone; 503 artifact_storage_unavailable\n\n**Next action:** Verify full downloaded size and SHA-256; request a fresh capability after expiry. [Worked workflow](/reference/http-workflows/)\n\nAuthorize a five-minute GET of the exact published version. Follow Location without forwarding the API bearer token. URLs are reusable capabilities until expiry, including after credential revocation; never log or persist them. Storage returns an attachment with application/octet-stream and no-store. HEAD authorizes the same GET capability without a response body.", "operationId": "get_artifact_content", "parameters": [ { "description": "Ready artifact readable by its creator or a current administrator of an accepting/producing run.", "in": "path", "name": "artifact_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "303": { "description": "Exact version verified and credential/availability rechecked before release.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "Location": { "description": "Secret temporary S3 GET URL; expires within 300 seconds.", "schema": { "type": "string" } }, "Referrer-Policy": { "description": "no-referrer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Query parameters are not accepted.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active user credential required, including a final recheck.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid, unknown or unauthorized artifact; unrelated standalone uploads remain private.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "artifact_not_ready: unpublished bytes cannot be downloaded.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "artifact_gone: artifact marked expired or unavailable; metadata is retained.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "artifact_unavailable or artifact_storage_unavailable. Retry; never fall back to another version.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Artifacts" ], "x-enumeray-contract": { "errors": [ "403 insufficient_scope", "404 not_found", "409 artifact_not_ready", "410 artifact_gone", "503 artifact_storage_unavailable" ], "guards": "For content, exact published version is verified and credential, membership and availability are rechecked before issuing a 303. Follow Location in a separate storage request without API bearer headers.", "method": "get", "next_action": "Verify full downloaded size and SHA-256; request a fresh capability after expiry.", "path": "/api/v1/artifacts/{artifact_id}/content", "purpose": "Authorize an exact-version five-minute object-storage download.", "retained": "Artifact UUID and published version/size/SHA-256; never retain capability URLs.", "retry": "Repeat GET using the same resource identity; each request rechecks current credential and resource authority.", "roles": "Artifact creator, or current administrator of a run that produced or accepted the exact artifact dependency. Unrelated standalone uploads remain private.", "scopes": [ "artifacts:download" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/audit/{kind}/{resource}": { "get": { "operationId": "selfservice_get_api_v1_audit__kind___resource_", "parameters": [ { "in": "path", "name": "kind", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "resource", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Continuation from next_cursor; management collections also accept after.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection_AuditEvent" } } }, "description": "Read resource-scoped audit history; kind is model or connector.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Read resource-scoped audit history; kind is model or connector.", "tags": [ "Self service" ] } }, "/api/v1/auth/config": { "get": { "operationId": "selfservice_get_api_v1_auth_config", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserAuthConfig" } } }, "description": "Public native-client OIDC configuration for browser login with S256 PKCE.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/HttpError" } }, "summary": "Public native-client OIDC configuration for browser login with S256 PKCE.", "tags": [ "Self service" ] } }, "/api/v1/collections": { "post": { "description": "Create a bounded immutable collection operation.\n\n**Credential scopes:** `uploads:create`\n\n**Resource authority:** Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.\n\n**Retry:** Create with saved key/body; replay member pages at their original index. Freeze/bind/complete repeat unchanged identities. Changed or overlapping page content conflicts.\n\n**Guards:** Freeze metadata before binding verified artifacts. Requested manifest_sha256 and sealed manifest_digest cover different records; use the published byte algorithm.\n\n**Retain:** Collection ID, original key/request, member order/pages, requested digest, member artifact UUIDs and sealed digest.\n\n**Specific failures:** 409 collection_conflict; 413 payload_too_large; 422 invalid_collection; 429 collection_quota; 503 collection_uncertain\n\n**Next action:** Inspect the retained operation and continue its next unfinished step. [Worked workflow](/reference/http-workflows/)\n\nAt most 64 KiB per request/page and 16 MiB per manifest. Freeze membership before binding members. Completion seals exact verified versions atomically. Replay original identities after uncertainty. Unknown/duplicate fields and query parameters are rejected, except the member cursor. Member pages contain at most 100 entries and 64 KiB; next_cursor is an immutable index, bound by the collection UUID. Every listed member is required. A sealed manifest remains historical evidence when bytes become unavailable.", "operationId": "userCollectionpost", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "create-empty-collection": { "description": "The exact digest input is the two UTF-8 bytes []. Empty collections need freeze and completion but no member page or upload.", "summary": "create-empty-collection", "value": { "logical_name": "empty-observations", "manifest_sha256": "T1PNoYwrqgwDVLtfmj7L5e0Sq02OEbqHPC8RFhICuUU=", "member_count": 0, "scientific_metadata": {}, "total_bytes": 0 } } }, "schema": { "$ref": "#/components/schemas/CollectionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "create-empty-collection": { "description": "The exact digest input is the two UTF-8 bytes []. Empty collections need freeze and completion but no member page or upload.", "summary": "create-empty-collection", "value": { "collection_id": "00000000-0000-4000-8000-000000000011", "request": { "logical_name": "empty-observations", "manifest_sha256": "T1PNoYwrqgwDVLtfmj7L5e0Sq02OEbqHPC8RFhICuUU=", "member_count": 0, "scientific_metadata": {}, "total_bytes": 0 } } } }, "schema": { "$ref": "#/components/schemas/CollectionReceipt" } } }, "description": "Original receipt or bounded current view.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown and unauthorized collections are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Frozen evidence conflict or members not verified.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds its bound.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "description": "Collection writes require application/json.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid manifest, paths, metadata or member evidence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "Collection admission limit exceeded.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Unavailable or uncertain acknowledgement; repeat original operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Immutable bounded collection metadata; member bytes use verified artifact uploads and downloads.", "tags": [ "Collections" ], "x-enumeray-contract": { "errors": [ "409 collection_conflict", "413 payload_too_large", "422 invalid_collection", "429 collection_quota", "503 collection_uncertain" ], "guards": "Freeze metadata before binding verified artifacts. Requested manifest_sha256 and sealed manifest_digest cover different records; use the published byte algorithm.", "method": "post", "next_action": "Inspect the retained operation and continue its next unfinished step.", "path": "/api/v1/collections", "purpose": "Create a bounded immutable collection operation.", "retained": "Collection ID, original key/request, member order/pages, requested digest, member artifact UUIDs and sealed digest.", "retry": "Create with saved key/body; replay member pages at their original index. Freeze/bind/complete repeat unchanged identities. Changed or overlapping page content conflicts.", "roles": "Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.", "scopes": [ "uploads:create" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/collections/{id}": { "get": { "description": "Inspect a collection and its requested or sealed identity.\n\n**Credential scopes:** `artifacts:read`\n\n**Resource authority:** Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.\n\n**Retry:** Create with saved key/body; replay member pages at their original index. Freeze/bind/complete repeat unchanged identities. Changed or overlapping page content conflicts.\n\n**Guards:** Freeze metadata before binding verified artifacts. Requested manifest_sha256 and sealed manifest_digest cover different records; use the published byte algorithm.\n\n**Retain:** Collection ID, original key/request, member order/pages, requested digest, member artifact UUIDs and sealed digest.\n\n**Specific failures:** 400 invalid_query; 403 insufficient_scope; 404 not_found: missing or unauthorized collection/run; 503 collection_uncertain\n\n**Next action:** Inspect the retained operation and continue its next unfinished step. [Worked workflow](/reference/http-workflows/)\n\nAt most 64 KiB per request/page and 16 MiB per manifest. Freeze membership before binding members. Completion seals exact verified versions atomically. Replay original identities after uncertainty. Unknown/duplicate fields and query parameters are rejected, except the member cursor. Member pages contain at most 100 entries and 64 KiB; next_cursor is an immutable index, bound by the collection UUID. Every listed member is required. A sealed manifest remains historical evidence when bytes become unavailable.", "operationId": "userCollectionget_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionView" } } }, "description": "Original receipt or bounded current view.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown and unauthorized collections are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Frozen evidence conflict or members not verified.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds its bound.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "description": "Collection writes require application/json.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid manifest, paths, metadata or member evidence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "Collection admission limit exceeded.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Unavailable or uncertain acknowledgement; repeat original operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Immutable bounded collection metadata; member bytes use verified artifact uploads and downloads.", "tags": [ "Collections" ], "x-enumeray-contract": { "errors": [ "400 invalid_query", "403 insufficient_scope", "404 not_found: missing or unauthorized collection/run", "503 collection_uncertain" ], "guards": "Freeze metadata before binding verified artifacts. Requested manifest_sha256 and sealed manifest_digest cover different records; use the published byte algorithm.", "method": "get", "next_action": "Inspect the retained operation and continue its next unfinished step.", "path": "/api/v1/collections/{id}", "purpose": "Inspect a collection and its requested or sealed identity.", "retained": "Collection ID, original key/request, member order/pages, requested digest, member artifact UUIDs and sealed digest.", "retry": "Create with saved key/body; replay member pages at their original index. Freeze/bind/complete repeat unchanged identities. Changed or overlapping page content conflicts.", "roles": "Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.", "scopes": [ "artifacts:read" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/collections/{id}/completion": { "put": { "description": "Atomically seal all member artifact/version identities.\n\n**Credential scopes:** `uploads:complete`\n\n**Resource authority:** Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.\n\n**Retry:** Create with saved key/body; replay member pages at their original index. Freeze/bind/complete repeat unchanged identities. Changed or overlapping page content conflicts.\n\n**Guards:** Freeze metadata before binding verified artifacts. Requested manifest_sha256 and sealed manifest_digest cover different records; use the published byte algorithm.\n\n**Retain:** Collection ID, original key/request, member order/pages, requested digest, member artifact UUIDs and sealed digest.\n\n**Specific failures:** 409 collection_conflict; 413 payload_too_large; 422 invalid_collection; 429 collection_quota; 503 collection_uncertain\n\n**Next action:** Inspect the retained operation and continue its next unfinished step. [Worked workflow](/reference/http-workflows/)\n\nAt most 64 KiB per request/page and 16 MiB per manifest. Freeze membership before binding members. Completion seals exact verified versions atomically. Replay original identities after uncertainty. Unknown/duplicate fields and query parameters are rejected, except the member cursor. Member pages contain at most 100 entries and 64 KiB; next_cursor is an immutable index, bound by the collection UUID. Every listed member is required. A sealed manifest remains historical evidence when bytes become unavailable.", "operationId": "userCollectionput_id_completion", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "complete-empty-collection": { "description": "The exact digest input is the two UTF-8 bytes []. Empty collections need freeze and completion but no member page or upload.", "summary": "complete-empty-collection", "value": {} } }, "schema": { "additionalProperties": false, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "complete-empty-collection": { "description": "The exact digest input is the two UTF-8 bytes []. Empty collections need freeze and completion but no member page or upload.", "summary": "complete-empty-collection", "value": { "available": true, "collection_id": "00000000-0000-4000-8000-000000000011", "manifest_digest": "T1PNoYwrqgwDVLtfmj7L5e0Sq02OEbqHPC8RFhICuUU=", "request": { "logical_name": "empty-observations", "manifest_sha256": "T1PNoYwrqgwDVLtfmj7L5e0Sq02OEbqHPC8RFhICuUU=", "member_count": 0, "scientific_metadata": {}, "total_bytes": 0 }, "state": "ready" } } }, "schema": { "$ref": "#/components/schemas/CollectionView" } } }, "description": "Original receipt or bounded current view.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown and unauthorized collections are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Frozen evidence conflict or members not verified.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds its bound.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "description": "Collection writes require application/json.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid manifest, paths, metadata or member evidence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "Collection admission limit exceeded.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Unavailable or uncertain acknowledgement; repeat original operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Immutable bounded collection metadata; member bytes use verified artifact uploads and downloads.", "tags": [ "Collections" ], "x-enumeray-contract": { "errors": [ "409 collection_conflict", "413 payload_too_large", "422 invalid_collection", "429 collection_quota", "503 collection_uncertain" ], "guards": "Freeze metadata before binding verified artifacts. Requested manifest_sha256 and sealed manifest_digest cover different records; use the published byte algorithm.", "method": "put", "next_action": "Inspect the retained operation and continue its next unfinished step.", "path": "/api/v1/collections/{id}/completion", "purpose": "Atomically seal all member artifact/version identities.", "retained": "Collection ID, original key/request, member order/pages, requested digest, member artifact UUIDs and sealed digest.", "retry": "Create with saved key/body; replay member pages at their original index. Freeze/bind/complete repeat unchanged identities. Changed or overlapping page content conflicts.", "roles": "Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.", "scopes": [ "uploads:complete" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/collections/{id}/freeze": { "put": { "description": "Freeze the exact requested member manifest before artifact binding.\n\n**Credential scopes:** `uploads:create`\n\n**Resource authority:** Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.\n\n**Retry:** Create with saved key/body; replay member pages at their original index. Freeze/bind/complete repeat unchanged identities. Changed or overlapping page content conflicts.\n\n**Guards:** Freeze metadata before binding verified artifacts. Requested manifest_sha256 and sealed manifest_digest cover different records; use the published byte algorithm.\n\n**Retain:** Collection ID, original key/request, member order/pages, requested digest, member artifact UUIDs and sealed digest.\n\n**Specific failures:** 409 collection_conflict; 413 payload_too_large; 422 invalid_collection; 429 collection_quota; 503 collection_uncertain\n\n**Next action:** Inspect the retained operation and continue its next unfinished step. [Worked workflow](/reference/http-workflows/)\n\nAt most 64 KiB per request/page and 16 MiB per manifest. Freeze membership before binding members. Completion seals exact verified versions atomically. Replay original identities after uncertainty. Unknown/duplicate fields and query parameters are rejected, except the member cursor. Member pages contain at most 100 entries and 64 KiB; next_cursor is an immutable index, bound by the collection UUID. Every listed member is required. A sealed manifest remains historical evidence when bytes become unavailable.", "operationId": "userCollectionput_id_freeze", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "freeze-empty-collection": { "description": "The exact digest input is the two UTF-8 bytes []. Empty collections need freeze and completion but no member page or upload.", "summary": "freeze-empty-collection", "value": {} } }, "schema": { "additionalProperties": false, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "freeze-empty-collection": { "description": "The exact digest input is the two UTF-8 bytes []. Empty collections need freeze and completion but no member page or upload.", "summary": "freeze-empty-collection", "value": { "collection_id": "00000000-0000-4000-8000-000000000011", "manifest_sha256": "T1PNoYwrqgwDVLtfmj7L5e0Sq02OEbqHPC8RFhICuUU=" } } }, "schema": { "$ref": "#/components/schemas/CollectionFreezeReceipt" } } }, "description": "Original receipt or bounded current view.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown and unauthorized collections are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Frozen evidence conflict or members not verified.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds its bound.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "description": "Collection writes require application/json.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid manifest, paths, metadata or member evidence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "Collection admission limit exceeded.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Unavailable or uncertain acknowledgement; repeat original operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Immutable bounded collection metadata; member bytes use verified artifact uploads and downloads.", "tags": [ "Collections" ], "x-enumeray-contract": { "errors": [ "409 collection_conflict", "413 payload_too_large", "422 invalid_collection", "429 collection_quota", "503 collection_uncertain" ], "guards": "Freeze metadata before binding verified artifacts. Requested manifest_sha256 and sealed manifest_digest cover different records; use the published byte algorithm.", "method": "put", "next_action": "Inspect the retained operation and continue its next unfinished step.", "path": "/api/v1/collections/{id}/freeze", "purpose": "Freeze the exact requested member manifest before artifact binding.", "retained": "Collection ID, original key/request, member order/pages, requested digest, member artifact UUIDs and sealed digest.", "retry": "Create with saved key/body; replay member pages at their original index. Freeze/bind/complete repeat unchanged identities. Changed or overlapping page content conflicts.", "roles": "Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.", "scopes": [ "uploads:create" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/collections/{id}/members": { "get": { "description": "Page member metadata using the returned immutable index cursor.\n\n**Credential scopes:** `artifacts:read`\n\n**Resource authority:** Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.\n\n**Retry:** Create with saved key/body; replay member pages at their original index. Freeze/bind/complete repeat unchanged identities. Changed or overlapping page content conflicts.\n\n**Guards:** Freeze metadata before binding verified artifacts. Requested manifest_sha256 and sealed manifest_digest cover different records; use the published byte algorithm.\n\n**Retain:** Collection ID, original key/request, member order/pages, requested digest, member artifact UUIDs and sealed digest.\n\n**Specific failures:** 400 invalid_query; 403 insufficient_scope; 404 not_found: missing or unauthorized collection/run; 503 collection_uncertain\n\n**Next action:** Inspect the retained operation and continue its next unfinished step. [Worked workflow](/reference/http-workflows/)\n\nAt most 64 KiB per request/page and 16 MiB per manifest. Freeze membership before binding members. Completion seals exact verified versions atomically. Replay original identities after uncertainty. Unknown/duplicate fields and query parameters are rejected, except the member cursor. Member pages contain at most 100 entries and 64 KiB; next_cursor is an immutable index, bound by the collection UUID. Every listed member is required. A sealed manifest remains historical evidence when bytes become unavailable.", "operationId": "userCollectionget_id_members", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "default": 0, "maximum": 10000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "empty-member-page": { "description": "The exact digest input is the two UTF-8 bytes []. Empty collections need freeze and completion but no member page or upload.", "summary": "empty-member-page", "value": { "items": [], "next_cursor": null } } }, "schema": { "$ref": "#/components/schemas/MemberPage" } } }, "description": "Original receipt or bounded current view.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown and unauthorized collections are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Frozen evidence conflict or members not verified.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds its bound.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "description": "Collection writes require application/json.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid manifest, paths, metadata or member evidence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "Collection admission limit exceeded.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Unavailable or uncertain acknowledgement; repeat original operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Immutable bounded collection metadata; member bytes use verified artifact uploads and downloads.", "tags": [ "Collections" ], "x-enumeray-contract": { "errors": [ "400 invalid_query", "403 insufficient_scope", "404 not_found: missing or unauthorized collection/run", "503 collection_uncertain" ], "guards": "Freeze metadata before binding verified artifacts. Requested manifest_sha256 and sealed manifest_digest cover different records; use the published byte algorithm.", "method": "get", "next_action": "Inspect the retained operation and continue its next unfinished step.", "path": "/api/v1/collections/{id}/members", "purpose": "Page member metadata using the returned immutable index cursor.", "retained": "Collection ID, original key/request, member order/pages, requested digest, member artifact UUIDs and sealed digest.", "retry": "Create with saved key/body; replay member pages at their original index. Freeze/bind/complete repeat unchanged identities. Changed or overlapping page content conflicts.", "roles": "Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.", "scopes": [ "artifacts:read" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/collections/{id}/members/{index}": { "put": { "description": "Write member metadata at the original zero-based index.\n\n**Credential scopes:** `uploads:create`\n\n**Resource authority:** Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.\n\n**Retry:** Create with saved key/body; replay member pages at their original index. Freeze/bind/complete repeat unchanged identities. Changed or overlapping page content conflicts.\n\n**Guards:** Freeze metadata before binding verified artifacts. Requested manifest_sha256 and sealed manifest_digest cover different records; use the published byte algorithm.\n\n**Retain:** Collection ID, original key/request, member order/pages, requested digest, member artifact UUIDs and sealed digest.\n\n**Specific failures:** 409 collection_conflict; 413 payload_too_large; 422 invalid_collection; 429 collection_quota; 503 collection_uncertain\n\n**Next action:** Inspect the retained operation and continue its next unfinished step. [Worked workflow](/reference/http-workflows/)\n\nAt most 64 KiB per request/page and 16 MiB per manifest. Freeze membership before binding members. Completion seals exact verified versions atomically. Replay original identities after uncertainty. Unknown/duplicate fields and query parameters are rejected, except the member cursor. Member pages contain at most 100 entries and 64 KiB; next_cursor is an immutable index, bound by the collection UUID. Every listed member is required. A sealed manifest remains historical evidence when bytes become unavailable.", "operationId": "userCollectionput_id_members_index", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "maximum": 9999, "minimum": 0, "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/MemberSpec" }, "maxItems": 10000, "type": "array" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionPageReceipt" } } }, "description": "Original receipt or bounded current view.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown and unauthorized collections are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Frozen evidence conflict or members not verified.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds its bound.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "description": "Collection writes require application/json.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid manifest, paths, metadata or member evidence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "Collection admission limit exceeded.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Unavailable or uncertain acknowledgement; repeat original operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Immutable bounded collection metadata; member bytes use verified artifact uploads and downloads.", "tags": [ "Collections" ], "x-enumeray-contract": { "errors": [ "409 collection_conflict", "413 payload_too_large", "422 invalid_collection", "429 collection_quota", "503 collection_uncertain" ], "guards": "Freeze metadata before binding verified artifacts. Requested manifest_sha256 and sealed manifest_digest cover different records; use the published byte algorithm.", "method": "put", "next_action": "Inspect the retained operation and continue its next unfinished step.", "path": "/api/v1/collections/{id}/members/{index}", "purpose": "Write member metadata at the original zero-based index.", "retained": "Collection ID, original key/request, member order/pages, requested digest, member artifact UUIDs and sealed digest.", "retry": "Create with saved key/body; replay member pages at their original index. Freeze/bind/complete repeat unchanged identities. Changed or overlapping page content conflicts.", "roles": "Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.", "scopes": [ "uploads:create" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/collections/{id}/members/{index}/artifact": { "put": { "description": "Bind an exact verified member artifact after freezing metadata.\n\n**Credential scopes:** `uploads:complete`\n\n**Resource authority:** Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.\n\n**Retry:** Create with saved key/body; replay member pages at their original index. Freeze/bind/complete repeat unchanged identities. Changed or overlapping page content conflicts.\n\n**Guards:** Freeze metadata before binding verified artifacts. Requested manifest_sha256 and sealed manifest_digest cover different records; use the published byte algorithm.\n\n**Retain:** Collection ID, original key/request, member order/pages, requested digest, member artifact UUIDs and sealed digest.\n\n**Specific failures:** 409 collection_conflict; 413 payload_too_large; 422 invalid_collection; 429 collection_quota; 503 collection_uncertain\n\n**Next action:** Inspect the retained operation and continue its next unfinished step. [Worked workflow](/reference/http-workflows/)\n\nAt most 64 KiB per request/page and 16 MiB per manifest. Freeze membership before binding members. Completion seals exact verified versions atomically. Replay original identities after uncertainty. Unknown/duplicate fields and query parameters are rejected, except the member cursor. Member pages contain at most 100 entries and 64 KiB; next_cursor is an immutable index, bound by the collection UUID. Every listed member is required. A sealed manifest remains historical evidence when bytes become unavailable.", "operationId": "userCollectionput_id_members_index_artifact", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "maximum": 9999, "minimum": 0, "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "artifact_id": { "format": "uuid", "type": "string" } }, "required": [ "artifact_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionBindingReceipt" } } }, "description": "Original receipt or bounded current view.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown and unauthorized collections are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Frozen evidence conflict or members not verified.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds its bound.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "description": "Collection writes require application/json.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid manifest, paths, metadata or member evidence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "Collection admission limit exceeded.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Unavailable or uncertain acknowledgement; repeat original operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Immutable bounded collection metadata; member bytes use verified artifact uploads and downloads.", "tags": [ "Collections" ], "x-enumeray-contract": { "errors": [ "409 collection_conflict", "413 payload_too_large", "422 invalid_collection", "429 collection_quota", "503 collection_uncertain" ], "guards": "Freeze metadata before binding verified artifacts. Requested manifest_sha256 and sealed manifest_digest cover different records; use the published byte algorithm.", "method": "put", "next_action": "Inspect the retained operation and continue its next unfinished step.", "path": "/api/v1/collections/{id}/members/{index}/artifact", "purpose": "Bind an exact verified member artifact after freezing metadata.", "retained": "Collection ID, original key/request, member order/pages, requested digest, member artifact UUIDs and sealed digest.", "retry": "Create with saved key/body; replay member pages at their original index. Freeze/bind/complete repeat unchanged identities. Changed or overlapping page content conflicts.", "roles": "Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.", "scopes": [ "uploads:complete" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/compute-grants": { "get": { "description": "Discover active compute grants available to the authenticated account.\n\n**Credential scopes:** `connectors:read`\n\n**Resource authority:** Named grant recipient; the grant does not confer connector administration.\n\n**Retry:** Repeat GET using the same resource identity; each request rechecks current credential and resource authority.\n\n**Guards:** Returned grants remain subject to current context and grant policy.\n\n**Retain:** Grant/context identities and pagination cursor.\n\n**Specific failures:** 403 insufficient_scope\n\n**Next action:** Select a personal grant for fresh publication registration. [Worked workflow](/reference/permissions/)", "operationId": "selfservice_get_api_v1_compute_grants", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Continuation from next_cursor; management collections also accept after.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection_AvailableGrant" } } }, "description": "Discover compute grants and contexts delegated to the caller.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Discover compute grants and contexts delegated to the caller.", "tags": [ "Self service" ], "x-enumeray-contract": { "errors": [ "403 insufficient_scope" ], "guards": "Returned grants remain subject to current context and grant policy.", "method": "get", "next_action": "Select a personal grant for fresh publication registration.", "path": "/api/v1/compute-grants", "purpose": "Discover active compute grants available to the authenticated account.", "retained": "Grant/context identities and pagination cursor.", "retry": "Repeat GET using the same resource identity; each request rechecks current credential and resource authority.", "roles": "Named grant recipient; the grant does not confer connector administration.", "scopes": [ "connectors:read" ], "workflow": "/reference/permissions/" } } }, "/api/v1/connectors": { "get": { "description": "List connectors administered by the authenticated account.\n\n**Credential scopes:** `connectors:read`\n\n**Resource authority:** Current connector owner/co-admin only; a compute grant alone does not add an entry.\n\n**Retry:** Repeat GET using the same resource identity; each request rechecks current credential and resource authority.\n\n**Guards:** Connector administration is separate from compute-grant discovery.\n\n**Retain:** Pagination cursor and account.\n\n**Specific failures:** 403 insufficient_scope\n\n**Next action:** Grant-only authors use GET /api/v1/compute-grants or enumeray connector grant available. [Worked workflow](/reference/permissions/)", "operationId": "selfservice_get_api_v1_connectors", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Continuation from next_cursor; management collections also accept after.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection_ConnectorSummary" } } }, "description": "List owned and co-administered connectors with ownership and configuration generations.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "List owned and co-administered connectors with ownership and configuration generations.", "tags": [ "Self service" ], "x-enumeray-contract": { "errors": [ "403 insufficient_scope" ], "guards": "Connector administration is separate from compute-grant discovery.", "method": "get", "next_action": "Grant-only authors use GET /api/v1/compute-grants or enumeray connector grant available.", "path": "/api/v1/connectors", "purpose": "List connectors administered by the authenticated account.", "retained": "Pagination cursor and account.", "retry": "Repeat GET using the same resource identity; each request rechecks current credential and resource authority.", "roles": "Current connector owner/co-admin only; a compute grant alone does not add an entry.", "scopes": [ "connectors:read" ], "workflow": "/reference/permissions/" } }, "post": { "operationId": "selfservice_post_api_v1_connectors", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorRegistration" } } }, "description": "Register a connector and issue a one-time enrollment token.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Register a connector and issue a one-time enrollment token.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}": { "get": { "operationId": "selfservice_get_api_v1_connectors__connector_id_", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorSummary" } } }, "description": "Inspect an administered connector, including archived history.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Inspect an administered connector, including archived history.", "tags": [ "Self service" ] }, "put": { "operationId": "selfservice_put_api_v1_connectors__connector_id_", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorUpdateReceipt" } } }, "description": "Change connector label and dispatch capacity using optimistic concurrency.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Change connector label and dispatch capacity using optimistic concurrency.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/archive": { "post": { "operationId": "selfservice_post_api_v1_connectors__connector_id__archive", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveReceipt" } } }, "description": "Archive the resource while preserving referenced execution history.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Archive the resource while preserving referenced execution history.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/authority": { "put": { "operationId": "selfservice_put_api_v1_connectors__connector_id__authority", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorAuthorityChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorLifecycleReceipt" } } }, "description": "Withdraw or restore connector-wide execution authority at the observed generation without changing maintenance or permanent revocations. Withdrawal prevents prelaunch work and requests pending-only scheduler cancellation; running jobs and delivery drain. Restoration never retries terminated work.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Withdraw or restore connector-wide execution authority at the observed generation without changing maintenance or permanent revocations. Withdrawal prevents prelaunch work and requests pending-only scheduler cancellation; running jobs and delivery drain. Restoration never retries terminated work.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/contexts": { "get": { "operationId": "selfservice_get_api_v1_connectors__connector_id__contexts", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Continuation from next_cursor; management collections also accept after.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection_ContextSummary" } } }, "description": "List permitted connector execution contexts.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "List permitted connector execution contexts.", "tags": [ "Self service" ] }, "post": { "operationId": "selfservice_post_api_v1_connectors__connector_id__contexts", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextRegistration" } } }, "description": "Create an immutable connector-controlled execution context.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Create an immutable connector-controlled execution context.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/contexts/{context_id}": { "get": { "operationId": "selfservice_get_api_v1_connectors__connector_id__contexts__context_id_", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "context_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextLifecycleStatus" } } }, "description": "Inspect operational context lifecycle, generation, retained work and retirement readiness. Requires connectors:read and current connector administration; historical retired contexts remain inspectable. Connector-wide shutdown and local cleanup require separate evidence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Inspect operational context lifecycle, generation, retained work and retirement readiness. Requires connectors:read and current connector administration; historical retired contexts remain inspectable. Connector-wide shutdown and local cleanup require separate evidence.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/contexts/{context_id}/configuration-retirements": { "put": { "operationId": "selfservice_put_api_v1_connectors__connector_id__contexts__context_id__configuration_retirements", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "context_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextLifecycleReceipt" } } }, "description": "Explicitly request retirement of obsolete publication configuration on a draining context, including abandoned candidates, at its expected generation. Requires connectors:manage and current connector administration. Reuse ordinary publication-retirement evidence; accepted work, delivery and shared references remain protected. Exact unchanged request/generation retries return the retained receipt.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Explicitly request retirement of obsolete publication configuration on a draining context, including abandoned candidates, at its expected generation. Requires connectors:manage and current connector administration. Reuse ordinary publication-retirement evidence; accepted work, delivery and shared references remain protected. Exact unchanged request/generation retries return the retained receipt.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/contexts/{context_id}/cutover": { "put": { "operationId": "selfservice_put_api_v1_connectors__connector_id__contexts__context_id__cutover", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "context_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextCutover" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextLifecycleReceipt" } } }, "description": "Cut over an active context using its expected generation after all live current publications have moved or been explicitly withdrawn. Requires connectors:manage and current connector administration. Close fresh grants, registration, activation, standard submissions and trials; explicitly drain or cancel only still-queued accepted work. Assigned work and delivery retain their original destination and independent controls. Exact unchanged request/generation retries return the retained receipt; changed stale requests conflict.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Cut over an active context using its expected generation after all live current publications have moved or been explicitly withdrawn. Requires connectors:manage and current connector administration. Close fresh grants, registration, activation, standard submissions and trials; explicitly drain or cancel only still-queued accepted work. Assigned work and delivery retain their original destination and independent controls. Exact unchanged request/generation retries return the retained receipt; changed stale requests conflict.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/contexts/{context_id}/metadata": { "put": { "operationId": "selfservice_put_api_v1_connectors__connector_id__contexts__context_id__metadata", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "context_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextMetadataUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextMetadataReceipt" } } }, "description": "Update descriptive context metadata at its observed generation without changing execution settings or retained publications.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Update descriptive context metadata at its observed generation without changing execution settings or retained publications.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/contexts/{context_id}/preflight": { "get": { "operationId": "read", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "context_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextPreflightStatus" } } }, "description": "", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "crate::management::preflight" ] } }, "/api/v1/connectors/{connector_id}/contexts/{context_id}/preflight/{request_id}": { "put": { "operationId": "request", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "context_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "request_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextPreflightStatus" } } }, "description": "", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "crate::management::preflight" ] } }, "/api/v1/connectors/{connector_id}/contexts/{context_id}/reopen": { "put": { "operationId": "selfservice_put_api_v1_connectors__connector_id__contexts__context_id__reopen", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "context_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextLifecycleReceipt" } } }, "description": "Reopen a draining context at its expected generation. Requires connectors:manage and current connector administration. Restore future eligibility without undoing cancellations, configuration-retirement requests, revocations or author activation choices. Retired contexts cannot reopen. Exact unchanged request/generation retries return the retained receipt.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Reopen a draining context at its expected generation. Requires connectors:manage and current connector administration. Restore future eligibility without undoing cancellations, configuration-retirement requests, revocations or author activation choices. Retired contexts cannot reopen. Exact unchanged request/generation retries return the retained receipt.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/contexts/{context_id}/replacement-plan": { "get": { "operationId": "selfservice_get_api_v1_connectors__connector_id__contexts__context_id__replacement_plan", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "context_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Continuation from next_cursor; management collections also accept after.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 128, "type": "string" } }, { "description": "Optional different context on a connector administered by the caller. Omit when decommissioning without a successor.", "in": "query", "name": "replacement_context_id", "required": false, "schema": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" } }, { "in": "query", "name": "section", "required": false, "schema": { "$ref": "#/components/schemas/ContextDependencySection" } }, { "description": "Alias for cursor. Supply only one and retain the same source, replacement and dependency section.", "in": "query", "name": "after", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextReplacementPlan" } } }, "description": "Read a paginated dependency plan for a context and optional replacement, including current/historical publications, candidates, grants, affected work, delivery obligations and responsible roles. Requires connectors:read and current connector administration; scientific data remains private. This writes no lifecycle or audit state.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Read a paginated dependency plan for a context and optional replacement, including current/historical publications, candidates, grants, affected work, delivery obligations and responsible roles. Requires connectors:read and current connector administration; scientific data remains private. This writes no lifecycle or audit state.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/contexts/{context_id}/retirement": { "put": { "operationId": "selfservice_put_api_v1_connectors__connector_id__contexts__context_id__retirement", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "context_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextLifecycleReceipt" } } }, "description": "Permanently archive a draining context at its expected generation only after all work, uncertainty, delivery, uploads and archives finish, all source publication configuration retires and the connector acknowledges final-reference removal. Requires connectors:manage and current connector administration. Preserve identity, grants, historical publications, provenance and revocations; local cleanup and whole-connector shutdown remain separate. Exact unchanged request/generation retries return the retained receipt.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Permanently archive a draining context at its expected generation only after all work, uncertainty, delivery, uploads and archives finish, all source publication configuration retires and the connector acknowledges final-reference removal. Requires connectors:manage and current connector administration. Preserve identity, grants, historical publications, provenance and revocations; local cleanup and whole-connector shutdown remain separate. Exact unchanged request/generation retries return the retained receipt.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/credentials": { "delete": { "operationId": "selfservice_delete_api_v1_connectors__connector_id__credentials", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorRevocationReceipt" } } }, "description": "Revoke connector credentials, expire outstanding enrollments, enter maintenance and withdraw execution authority. Existing jobs are not stopped; control and delivery require replacement enrollment.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Revoke connector credentials, expire outstanding enrollments, enter maintenance and withdraw execution authority. Existing jobs are not stopped; control and delivery require replacement enrollment.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/diagnostics": { "get": { "operationId": "selfservice_get_api_v1_connectors__connector_id__diagnostics", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "description": "Select one context belonging to this connector for setup readiness. Stored evidence only; request fresh host checks explicitly through preflight.", "in": "query", "name": "context_id", "required": false, "schema": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorDiagnostics" } } }, "description": "Inspect authenticated contact, session ownership, maintenance, authority and retained work. Optionally select one context for read-only setup readiness and corrective guidance; this never requests host checks. Maintenance completes only after assigned work, uploads and configured archives settle; queued work remains for resume.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Inspect authenticated contact, session ownership, maintenance, authority and retained work. Optionally select one context for read-only setup readiness and corrective guidance; this never requests host checks. Maintenance completes only after assigned work, uploads and configured archives settle; queued work remains for resume.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/enrollments": { "post": { "operationId": "selfservice_post_api_v1_connectors__connector_id__enrollments", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorEnrollment" } } }, "description": "Create a replacement enrollment; machine identity makes interrupted completion safely replayable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Create a replacement enrollment; machine identity makes interrupted completion safely replayable.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/grants": { "get": { "operationId": "selfservice_get_api_v1_connectors__connector_id__grants", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Continuation from next_cursor; management collections also accept after.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection_ComputeGrant" } } }, "description": "List compute grants; delegated users see only their own grants.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "List compute grants; delegated users see only their own grants.", "tags": [ "Self service" ] }, "post": { "operationId": "selfservice_post_api_v1_connectors__connector_id__grants", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeGrant" } } }, "description": "Delegate compute access to a model administrator.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Delegate compute access to a model administrator.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/grants/{grant_id}": { "delete": { "operationId": "selfservice_delete_api_v1_connectors__connector_id__grants__grant_id_", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "grant_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokedGrant" } } }, "description": "Revoke compute access; block new dispatch and request pending-work cancellation while existing execution drains.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Revoke compute access; block new dispatch and request pending-work cancellation while existing execution drains.", "tags": [ "Self service" ] }, "get": { "operationId": "selfservice_get_api_v1_connectors__connector_id__grants__grant_id_", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "grant_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeGrant" } } }, "description": "Inspect current compute-grant identity, limits, generation and revocation state. Requires connectors:read; current connector administrators and the grant holder may read, including revoked grants.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Inspect current compute-grant identity, limits, generation and revocation state. Requires connectors:read; current connector administrators and the grant holder may read, including revoked grants.", "tags": [ "Self service" ] }, "put": { "operationId": "selfservice_put_api_v1_connectors__connector_id__grants__grant_id_", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "grant_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeGrant" } } }, "description": "Replace both grant limits at the observed generation, preserving identity and publications. Requires connectors:manage and current connector administration. Lower limits fence fresh admission/claims while accepted and assigned work drains. Changed requests increment generation and audit once; unchanged current-generation requests do neither. Stale generations, including identical retries after a lost reply, conflict: inspect before another deliberate update. Revoked grants and archived connectors/contexts cannot be updated; draining contexts remain draining.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Replace both grant limits at the observed generation, preserving identity and publications. Requires connectors:manage and current connector administration. Lower limits fence fresh admission/claims while accepted and assigned work drains. Changed requests increment generation and audit once; unchanged current-generation requests do neither. Stale generations, including identical retries after a lost reply, conflict: inspect before another deliberate update. Revoked grants and archived connectors/contexts cannot be updated; draining contexts remain draining.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/members": { "get": { "operationId": "selfservice_get_api_v1_connectors__connector_id__members", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceMembers" } } }, "description": "Inspect the owner, co-admins, and concurrency generation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Inspect the owner, co-admins, and concurrency generation.", "tags": [ "Self service" ] }, "post": { "operationId": "selfservice_post_api_v1_connectors__connector_id__members", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipReceipt" } } }, "description": "Add a co-admin; only the resource owner controls membership.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Add a co-admin; only the resource owner controls membership.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/members/{user_id}": { "delete": { "operationId": "selfservice_delete_api_v1_connectors__connector_id__members__user_id_", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "user_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "remove-connector-member": { "description": "Valid one-time enrollment shape and removal of an existing co-administrator. Fixture verifier is SHA-256 of a nonsecret fixture token.", "summary": "remove-connector-member", "value": { "expected_generation": 2 } } }, "schema": { "$ref": "#/components/schemas/GenerationChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "remove-connector-member": { "description": "Valid one-time enrollment shape and removal of an existing co-administrator. Fixture verifier is SHA-256 of a nonsecret fixture token.", "summary": "remove-connector-member", "value": { "co_admin": false, "generation": 3, "user_id": "00000000-0000-4000-8000-000000000007" } } }, "schema": { "$ref": "#/components/schemas/MembershipReceipt" } } }, "description": "Remove a co-admin and their immediate resource-admin authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Remove a co-admin and their immediate resource-admin authority.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/ownership-transfers": { "post": { "operationId": "selfservice_post_api_v1_connectors__connector_id__ownership_transfers", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferProposalReceipt" } } }, "description": "Propose ownership transfer; the recipient must explicitly accept.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Propose ownership transfer; the recipient must explicitly accept.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/runs": { "get": { "operationId": "selfservice_get_api_v1_connectors__connector_id__runs", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Continuation from next_cursor; management collections also accept after.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection_OperationalRun" } } }, "description": "Inspect operational run metadata without private model inputs or outputs.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Inspect operational run metadata without private model inputs or outputs.", "tags": [ "Self service" ] } }, "/api/v1/connectors/{connector_id}/state": { "put": { "operationId": "selfservice_put_api_v1_connectors__connector_id__state", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorStateChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorLifecycleReceipt" } } }, "description": "Pause or resume fresh acceptance and claims at the observed generation. Maintenance retains queued work and permits assigned work, pending allocations, execution and delivery to finish; it never restores withdrawn authority. Same-state requests at the current generation do not mutate or audit again.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Pause or resume fresh acceptance and claims at the observed generation. Maintenance retains queued work and permits assigned work, pending allocations, execution and delivery to finish; it never restores withdrawn authority. Same-state requests at the current generation do not mutate or audit again.", "tags": [ "Self service" ] } }, "/api/v1/me": { "get": { "operationId": "me", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } }, "description": "The authenticated user's identity and current user permissions.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, malformed, unknown, revoked, or wrong-kind credential. All use code unauthenticated.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication could not be checked before its database deadline. Code authentication_unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Identity" ] } }, "/api/v1/models": { "get": { "operationId": "list_models", "parameters": [ { "description": "Page size; defaults to 20.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque continuation issued for this user and collection.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } }, "description": "Discover visible models according to listed/unlisted visibility, grants, and invitations.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid, unknown, duplicate, or oversized pagination parameters. Code invalid_pagination.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A valid user bearer token is required. Code unauthenticated.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication or discovery could not complete before its database deadline.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Models" ] }, "post": { "operationId": "selfservice_post_api_v1_models", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedModel" } } }, "description": "Create a model owned by the authenticated caller.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Create a model owned by the authenticated caller.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}": { "get": { "operationId": "get_model", "parameters": [ { "description": "Stable catalog model ID.", "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedModel" } } }, "description": "Model metadata and current publication. Listed restricted models expose metadata; the full contract requires execution access or model administration.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A valid user bearer token is required. Code unauthenticated.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Model is absent or inaccessible. Code not_found.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication or discovery could not complete before its database deadline.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Models" ] } }, "/api/v1/models/{model_id}/access-policy": { "get": { "operationId": "selfservice_get_api_v1_models__model_id__access_policy", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessPolicy" } } }, "description": "Inspect model access and catalogue visibility policy.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Inspect model access and catalogue visibility policy.", "tags": [ "Self service" ] }, "put": { "operationId": "selfservice_put_api_v1_models__model_id__access_policy", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessPolicyUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessPolicy" } } }, "description": "Choose open, request, or invite access at the observed generation; omitted or null visibility preserves the existing value.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Choose open, request, or invite access at the observed generation; omitted or null visibility preserves the existing value.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/access-requests": { "get": { "operationId": "selfservice_get_api_v1_models__model_id__access_requests", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Continuation from next_cursor; management collections also accept after.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection_AccessRequestSummary" } } }, "description": "List access requests visible to the caller.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "List access requests visible to the caller.", "tags": [ "Self service" ] }, "post": { "operationId": "selfservice_post_api_v1_models__model_id__access_requests", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessRequestCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessRequestReceipt" } } }, "description": "Request model access; repeated requests preserve the existing pending request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Request model access; repeated requests preserve the existing pending request.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/access-requests/{request_id}": { "put": { "operationId": "selfservice_put_api_v1_models__model_id__access_requests__request_id_", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "request_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessRequestDecision" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessDecisionReceipt" } } }, "description": "Approve/reject as a model administrator or withdraw your own request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Approve/reject as a model administrator or withdraw your own request.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/access/{user_id}": { "put": { "operationId": "selfservice_put_api_v1_models__model_id__access__user_id_", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "user_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessReceipt" } } }, "description": "Explicitly grant or block model execution for a user.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Explicitly grant or block model execution for a user.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/archive": { "post": { "operationId": "selfservice_post_api_v1_models__model_id__archive", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveReceipt" } } }, "description": "Archive the resource while preserving referenced execution history.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Archive the resource while preserving referenced execution history.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/invitations": { "get": { "operationId": "selfservice_get_api_v1_models__model_id__invitations", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Continuation from next_cursor; management collections also accept after.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection_InvitationSummary" } } }, "description": "List model invitations without acceptance secrets.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "List model invitations without acceptance secrets.", "tags": [ "Self service" ] }, "post": { "operationId": "selfservice_post_api_v1_models__model_id__invitations", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "invite-email": { "description": "Alternative recipient forms; each request has exactly one recipient. Tokens are shape-valid inert fixtures, never usable credentials.", "summary": "invite-email", "value": { "recipient_email": "colleague@example.org", "recipient_id": null } }, "invite-user": { "description": "Alternative recipient forms; each request has exactly one recipient. Tokens are shape-valid inert fixtures, never usable credentials.", "summary": "invite-user", "value": { "recipient_email": null, "recipient_id": "00000000-0000-4000-8000-000000000007" } } }, "schema": { "$ref": "#/components/schemas/InvitationCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "invite-email": { "description": "Alternative recipient forms; each request has exactly one recipient. Tokens are shape-valid inert fixtures, never usable credentials.", "summary": "invite-email", "value": { "expires_at": "2026-11-03T10:00:00Z", "id": "00000000-0000-4000-8000-000000000005", "model_id": "scalar-double", "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "invite-user": { "description": "Alternative recipient forms; each request has exactly one recipient. Tokens are shape-valid inert fixtures, never usable credentials.", "summary": "invite-user", "value": { "expires_at": "2026-11-03T10:00:00Z", "id": "00000000-0000-4000-8000-000000000006", "model_id": "scalar-double", "token": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" } } }, "schema": { "$ref": "#/components/schemas/InvitationReceipt" } } }, "description": "Create a seven-day recipient-bound invitation; return its secret once.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Create a seven-day recipient-bound invitation; return its secret once.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/invitations/accept": { "post": { "operationId": "selfservice_post_api_v1_models__model_id__invitations_accept", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "accept-invitation": { "description": "Alternative recipient forms; each request has exactly one recipient. Tokens are shape-valid inert fixtures, never usable credentials.", "summary": "accept-invitation", "value": { "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } } }, "schema": { "$ref": "#/components/schemas/InvitationAcceptance" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "accept-invitation": { "description": "Alternative recipient forms; each request has exactly one recipient. Tokens are shape-valid inert fixtures, never usable credentials.", "summary": "accept-invitation", "value": { "accepted": true, "id": "00000000-0000-4000-8000-000000000005" } } }, "schema": { "$ref": "#/components/schemas/AcceptanceReceipt" } } }, "description": "Accept the caller's unexpired invitation; repeated acceptance returns the original result.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Accept the caller's unexpired invitation; repeated acceptance returns the original result.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/members": { "get": { "operationId": "selfservice_get_api_v1_models__model_id__members", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceMembers" } } }, "description": "Inspect the owner, co-admins, and concurrency generation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Inspect the owner, co-admins, and concurrency generation.", "tags": [ "Self service" ] }, "post": { "operationId": "selfservice_post_api_v1_models__model_id__members", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipReceipt" } } }, "description": "Add a co-admin; only the resource owner controls membership.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Add a co-admin; only the resource owner controls membership.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/members/{user_id}": { "delete": { "operationId": "selfservice_delete_api_v1_models__model_id__members__user_id_", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "user_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipReceipt" } } }, "description": "Remove a co-admin and their immediate resource-admin authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Remove a co-admin and their immediate resource-admin authority.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/ownership-transfers": { "post": { "operationId": "selfservice_post_api_v1_models__model_id__ownership_transfers", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferProposalReceipt" } } }, "description": "Propose ownership transfer; the recipient must explicitly accept.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Propose ownership transfer; the recipient must explicitly accept.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/publications": { "get": { "operationId": "selfservice_get_api_v1_models__model_id__publications", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Continuation from next_cursor; management collections also accept after.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection_PublicationSummary" } } }, "description": "List immutable candidates, readiness, publications, and installation descriptors.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "List immutable candidates, readiness, publications, and installation descriptors.", "tags": [ "Self service" ] }, "post": { "operationId": "selfservice_post_api_v1_models__model_id__publications", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationRegistration" } } }, "description": "Register a model installation using a current compute grant; connector validation determines readiness.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Register a model installation using a current compute grant; connector validation determines readiness.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/publications/{publication_id}": { "delete": { "operationId": "selfservice_delete_api_v1_models__model_id__publications__publication_id_", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "publication_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationRevocationReceipt" } } }, "description": "Permanently revoke this exact publication. Identical retries preserve the revocation timestamp; accepted history and running result collection remain available.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Permanently revoke this exact publication. Identical retries preserve the revocation timestamp; accepted history and running result collection remain available.", "tags": [ "Self service" ] }, "get": { "operationId": "selfservice_get_api_v1_models__model_id__publications__publication_id_", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "publication_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationDetail" } } }, "description": "Inspect a candidate publication and connector validation results.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Inspect a candidate publication and connector validation results.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/publications/{publication_id}/activation": { "post": { "operationId": "selfservice_post_api_v1_models__model_id__publications__publication_id__activation", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "publication_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationActivation" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationActivationReceipt" } } }, "description": "Atomically publish a validated candidate if the current-publication precondition still holds.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Atomically publish a validated candidate if the current-publication precondition still holds.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/publications/{publication_id}/delegations": { "get": { "operationId": "selfservice_get_api_v1_models__model_id__publications__publication_id__delegations", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "publication_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Continuation from next_cursor; management collections also accept after.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection_PublicationDelegation" } } }, "description": "List retained named handoffs; current model administration and models:read are required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "List retained named handoffs; current model administration and models:read are required.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/publications/{publication_id}/delegations/{delegation_id}": { "delete": { "operationId": "selfservice_delete_api_v1_models__model_id__publications__publication_id__delegations__delegation_id_", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "publication_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "delegation_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationDelegation" } } }, "description": "Permanently revoke a handoff as captured grant holder or current model owner, using models:manage and the observed model generation. Replays retain revocation. Already published standard execution remains available under its existing authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Permanently revoke a handoff as captured grant holder or current model owner, using models:manage and the observed model generation. Replays retain revocation. Already published standard execution remains available under its existing authority.", "tags": [ "Self service" ] }, "get": { "operationId": "selfservice_get_api_v1_models__model_id__publications__publication_id__delegations__delegation_id_", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "publication_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "delegation_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationDelegation" } } }, "description": "Inspect one retained handoff and its permanent revocation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Inspect one retained handoff and its permanent revocation.", "tags": [ "Self service" ] }, "put": { "operationId": "selfservice_put_api_v1_models__model_id__publications__publication_id__delegations__delegation_id_", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "publication_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "delegation_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationDelegationCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationDelegation" } } }, "description": "Delegate trials and activation to a named active model administrator under the captured grant. Only its active holder may create a handoff; models:manage and the observed model generation are required. Identical UUID/request retries retain the original identity and revocation; different data conflicts. No redelegation or grant substitution.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Delegate trials and activation to a named active model administrator under the captured grant. Only its active holder may create a handoff; models:manage and the observed model generation are required. Identical UUID/request retries retain the original identity and revocation; different data conflicts. No redelegation or grant substitution.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/publications/{publication_id}/retirement": { "put": { "operationId": "selfservice_put_api_v1_models__model_id__publications__publication_id__retirement", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "publication_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationRetirement" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationRetirementReceipt" } } }, "description": "Request retirement of one publication's retained configuration at the observed model generation. Exact retries return the original receipt. Current publications require revocation or model archiving first. Accepted work and pending delivery defer retirement; installation revocations and historical provenance remain permanent.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Request retirement of one publication's retained configuration at the observed model generation. Exact retries return the original receipt. Current publications require revocation or model archiving first. Accepted work and pending delivery defer retirement; installation revocations and historical provenance remain permanent.", "tags": [ "Self service" ] } }, "/api/v1/models/{model_id}/runs": { "get": { "operationId": "selfservice_get_api_v1_models__model_id__runs", "parameters": [ { "in": "path", "name": "model_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Continuation from next_cursor; management collections also accept after.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection_ManagedRun" } } }, "description": "Inspect runs submitted to a model; current model administrators can access full run data.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Inspect runs submitted to a model; current model administrators can access full run data.", "tags": [ "Self service" ] } }, "/api/v1/openapi.json": { "get": { "operationId": "document", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OpenAPI 3.1 specification for this service version", "headers": { "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "default": { "$ref": "#/components/responses/HttpError" } }, "summary": "Return the generated specification for the currently implemented endpoints.", "tags": [] } }, "/api/v1/ownership-transfers/{transfer_id}/accept": { "post": { "operationId": "selfservice_post_api_v1_ownership_transfers__transfer_id__accept", "parameters": [ { "in": "path", "name": "transfer_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferAcceptance" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferAcceptanceReceipt" } } }, "description": "Accept an unexpired ownership transfer addressed to this account, optionally guarding its resource kind and ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The transfer's resource differs from the supplied kind/ID (ownership_transfer_resource_mismatch), the proposal expired, or the resource generation changed.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A nonempty acceptance body requires an application/json or application/*+json content type.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Accept an unexpired ownership transfer addressed to this account, optionally guarding its resource kind and ID.", "tags": [ "Self service" ] } }, "/api/v1/runs": { "get": { "description": "List the authenticated submitter's own run history.\n\n**Credential scopes:** `runs:read`\n\n**Resource authority:** Run submitter; model-administrator history uses the model run-history route.\n\n**Retry:** Repeat GET using the same resource identity; each request rechecks current credential and resource authority.\n\n**Guards:** This personal inventory is creator-scoped.\n\n**Retain:** User identity, filters and opaque cursor.\n\n**Specific failures:** 400 invalid_pagination; 403 insufficient_scope\n\n**Next action:** Inspect a returned run or use model run history for administrative investigation. [Worked workflow](/reference/http-workflows/)", "operationId": "list_runs", "parameters": [ { "description": "Maximum runs per page.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque continuation cursor, scoped to this user and these filters.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 2048, "type": "string" } }, { "description": "Filter by exact model identity.", "in": "query", "name": "model_id", "required": false, "schema": { "maxLength": 64, "type": "string" } }, { "description": "Filter by current public run state.", "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/RunState" } }, { "description": "Exclusive lower creation-time bound in RFC3339, at most six fractional digits.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Exclusive upper creation-time bound in RFC3339, at most six fractional digits.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunList" } } }, "description": "Only this creator's run summaries, with an opaque continuation cursor. Model-grant revocation does not remove access to accepted work.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid, unknown, duplicate, or incompatible filters, limits, or cursor. Code invalid_pagination.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An active user credential is required. Code unauthenticated.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication or run inspection is temporarily unavailable. Code run_inspection_unavailable for inspection failures.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Runs" ], "x-enumeray-contract": { "errors": [ "400 invalid_pagination", "403 insufficient_scope" ], "guards": "This personal inventory is creator-scoped.", "method": "get", "next_action": "Inspect a returned run or use model run history for administrative investigation.", "path": "/api/v1/runs", "purpose": "List the authenticated submitter's own run history.", "retained": "User identity, filters and opaque cursor.", "retry": "Repeat GET using the same resource identity; each request rechecks current credential and resource authority.", "roles": "Run submitter; model-administrator history uses the model run-history route.", "scopes": [ "runs:read" ], "workflow": "/reference/http-workflows/" } }, "post": { "description": "Accept one durable scientific execution intent.\n\n**Credential scopes:** `runs:create`\n\n**Resource authority:** Authorized model user; candidate trials additionally require models:manage and current model-administrator/captured-grant or named-delegation authority.\n\n**Retry:** Persist the request and Idempotency-Key before sending; repeat both unchanged after a lost reply. The same account/key returns the original acceptance receipt, not current run status.\n\n**Guards:** Explicit expected_publication_id, current access/admission and compatible declared inputs. Keys identify semantic requests and belong to the user, not one credential.\n\n**Retain:** API/account, full original body, Idempotency-Key and returned run/receipt identities.\n\n**Specific failures:** 409 idempotency_conflict; 413 payload_too_large; 422 invalid_inputs or invalid_artifact_input; 429 queue capacity\n\n**Next action:** Inspect the recovered run; a deliberate new execution requires a new key. [Worked workflow](/reference/http-workflows/)\n\nRun creation requires model_id, expected_publication_id, inputs. Successful retries return their original receipt even after publication/access changes. New work with a stale publication returns 409 publication_changed. ", "operationId": "create_run", "parameters": [ { "description": "Required once. Scoped to this user and run creation; retain the same key and semantic request after a lost response. Successful keys do not expire.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "accepted-run": { "description": "One accepted scalar run, followed through coherent queued, running and terminal observations. Replay returns the original queued receipt, not the current inspection.", "summary": "accepted-run", "value": { "expected_publication_id": "scalar-double-r1", "inputs": { "value": 2 }, "model_id": "scalar-double" } }, "invalid-scientific-input": { "description": "Only authorized scientific validation failures include bounded scientific-schema violations; authentication errors do not.", "summary": "invalid-scientific-input", "value": { "expected_publication_id": "scalar-double-r1", "inputs": { "value": "wrong scientific type" }, "model_id": "scalar-double" } }, "replayed-acceptance": { "description": "One accepted scalar run, followed through coherent queued, running and terminal observations. Replay returns the original queued receipt, not the current inspection.", "summary": "replayed-acceptance", "value": { "expected_publication_id": "scalar-double-r1", "inputs": { "value": 2 }, "model_id": "scalar-double" } } }, "schema": { "$ref": "#/components/schemas/RunSubmission" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/MultipartSubmission" } } }, "description": "Exact publication and fully specified inputs. Omitted purpose means standard and requires the current publication with public admission open. candidate_trial requires runs:create plus models:manage, current model administration/execution access and ownership of the captured compute grant or an exact active publication_delegation_id; it permits ready or published retained candidates without altering public admission. Fresh trials reject retirement, revocation, unavailable installations and maintenance. Trial intent persists through activation; execution success is advisory. JSON supports declared stored-artifact references. Multipart contains one application/json request part with this envelope, and at most 8 uniquely named attachment parts with explicit parameter-free media types. Only declared file inputs recognize closed {attachment: part-name} references; all attachments must be used. Parts may occur in any order; filenames are ignored. Total bytes obey ENUMERAY_MAX_REQUEST_BODY_BYTES (default 1 MiB, maximum 16 MiB), JSON part at most 1 MiB and inputs at most 64 KiB. Body deadline 60 seconds, staging deadline 120 seconds, four concurrent multipart submissions per process. Unknown/duplicate envelope fields and query parameters are rejected. JSON suffix media types (application/*+json) are also supported.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "accepted-run": { "description": "One accepted scalar run, followed through coherent queued, running and terminal observations. Replay returns the original queued receipt, not the current inspection.", "summary": "accepted-run", "value": { "created_at": "2026-11-02T10:00:00Z", "model_id": "scalar-double", "publication_id": "scalar-double-r1", "purpose": "standard", "run_id": "00000000-0000-4000-8000-000000000001", "state": "queued" } }, "replayed-acceptance": { "description": "One accepted scalar run, followed through coherent queued, running and terminal observations. Replay returns the original queued receipt, not the current inspection.", "summary": "replayed-acceptance", "value": { "created_at": "2026-11-02T10:00:00Z", "model_id": "scalar-double", "publication_id": "scalar-double-r1", "purpose": "standard", "run_id": "00000000-0000-4000-8000-000000000001", "state": "queued" } } }, "schema": { "$ref": "#/components/schemas/SubmissionReceipt" } } }, "description": "One run was durably accepted. Equivalent retries return the same initial receipt, even if the run has since progressed. Location identifies its run-detail resource.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "Location": { "description": "Relative run location: /api/v1/runs/{run_id}.", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON/multipart framing, duplicate parts, unsupported part headers or query parameters (bad_request), or a missing, repeated, or invalid Idempotency-Key (invalid_idempotency_key).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "examples": { "unauthenticated-run": { "description": "Only authorized scientific validation failures include bounded scientific-schema violations; authentication errors do not.", "summary": "unauthenticated-run", "value": { "code": "unauthenticated", "message": "A valid user bearer token is required.", "request_id": "00000000-0000-4000-8000-000000000012" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A valid active user credential is required. Code unauthenticated.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not allow run creation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The exact publication is absent or inaccessible. Code not_found.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The multipart HTTP body did not finish within 60 seconds. Code request_timeout; no work was accepted.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflicting operation key (idempotency_conflict), changed expected publication (publication_changed), unavailable publication (publication_unavailable).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The request, multipart JSON part, attachment count/file size or input JSON exceeds its finite byte or decimal-storage budget. Code payload_too_large.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A JSON or multipart/form-data content type is required. Code unsupported_media_type.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "examples": { "invalid-scientific-input": { "description": "Only authorized scientific validation failures include bounded scientific-schema violations; authentication errors do not.", "summary": "invalid-scientific-input", "value": { "code": "invalid_inputs", "details": { "truncated": false, "violations": [ { "correction": "Use a number.", "position": "/value", "position_redacted": false, "rule": "type" } ] }, "message": "Inputs do not satisfy the publication schema or supported JSON storage limits.", "request_id": "00000000-0000-4000-8000-000000000013" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The envelope or identifiers are invalid (invalid_request), inputs violate their schema, reference shape, storage, or nesting restrictions (invalid_inputs), an artifact is missing, private, not ready, or incompatible (invalid_artifact_input), or stored attachment evidence does not match (upload_verification_failed). Authorized schema failures include bounded position/rule/correction details; other failures omit details.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The service queue, user's queue or multipart capacity is full. Codes queue_full, user_queue_full and multipart_busy.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication or submission is unavailable; storage_not_configured means no managed upload destination is selected. Code submission_uncertain means the commit outcome is unknown: retry the same key and semantic request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Runs" ], "x-enumeray-contract": { "errors": [ "409 idempotency_conflict", "413 payload_too_large", "422 invalid_inputs or invalid_artifact_input", "429 queue capacity" ], "guards": "Explicit expected_publication_id, current access/admission and compatible declared inputs. Keys identify semantic requests and belong to the user, not one credential.", "method": "post", "next_action": "Inspect the recovered run; a deliberate new execution requires a new key.", "path": "/api/v1/runs", "purpose": "Accept one durable scientific execution intent.", "retained": "API/account, full original body, Idempotency-Key and returned run/receipt identities.", "retry": "Persist the request and Idempotency-Key before sending; repeat both unchanged after a lost reply. The same account/key returns the original acceptance receipt, not current run status.", "roles": "Authorized model user; candidate trials additionally require models:manage and current model-administrator/captured-grant or named-delegation authority.", "scopes": [ "runs:create" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/runs/{id}/collections": { "get": { "description": "List committed output collections in declared-name order.\n\n**Credential scopes:** `artifacts:read`\n\n**Resource authority:** Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.\n\n**Retry:** Repeat GET using the same resource identity; each request rechecks current credential and resource authority.\n\n**Guards:** No mutation or execution authority is granted.\n\n**Retain:** Run identity; opaque cursor where returned.\n\n**Specific failures:** 400 invalid_query; 403 insufficient_scope; 404 not_found: missing or unauthorized collection/run; 503 collection_uncertain\n\n**Next action:** Inspect current state; follow exact referenced artifact identities. [Worked workflow](/reference/http-workflows/)", "operationId": "runCollections", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "no-run-output-collections": { "description": "The exact digest input is the two UTF-8 bytes []. Empty collections need freeze and completion but no member page or upload.", "summary": "no-run-output-collections", "value": { "items": [], "next_cursor": null } } }, "schema": { "properties": { "items": { "items": { "properties": { "collection": { "$ref": "#/components/schemas/CollectionSummary" }, "output_name": { "type": "string" } }, "required": [ "output_name", "collection" ], "type": "object" }, "maxItems": 64, "type": "array" }, "next_cursor": { "type": "null" } }, "required": [ "items", "next_cursor" ], "type": "object" } } }, "description": "At most 64 committed output collection summaries.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown or unauthorized run.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "List committed output collections in declared-name order.", "tags": [ "Collections" ], "x-enumeray-contract": { "errors": [ "400 invalid_query", "403 insufficient_scope", "404 not_found: missing or unauthorized collection/run", "503 collection_uncertain" ], "guards": "No mutation or execution authority is granted.", "method": "get", "next_action": "Inspect current state; follow exact referenced artifact identities.", "path": "/api/v1/runs/{id}/collections", "purpose": "List committed output collections in declared-name order.", "retained": "Run identity; opaque cursor where returned.", "retry": "Repeat GET using the same resource identity; each request rechecks current credential and resource authority.", "roles": "Creator of a user-upload collection for mutations; producing output collections are published only by their assignment connector/session. Reads additionally permit current administrators of an accepting or producing run.", "scopes": [ "artifacts:read" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/runs/{run_id}": { "get": { "description": "Inspect accepted inputs, immutable requirements and current run state.\n\n**Credential scopes:** `runs:read`\n\n**Resource authority:** Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.\n\n**Retry:** Repeat GET using the same resource identity; each request rechecks current credential and resource authority.\n\n**Guards:** No mutation or execution authority is granted.\n\n**Retain:** Run identity; opaque cursor where returned.\n\n**Specific failures:** 403 insufficient_scope; 404 not_found: missing or unauthorized resource\n\n**Next action:** Inspect current state; follow exact referenced artifact identities. [Worked workflow](/reference/http-workflows/)", "operationId": "get_run", "parameters": [ { "description": "Accepted run identity.", "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "queued-run": { "description": "One accepted scalar run, followed through coherent queued, running and terminal observations. Replay returns the original queued receipt, not the current inspection.", "summary": "queued-run", "value": { "blocked_reason": null, "cancellation": null, "cancelled_at": null, "context_id": "lab-cpu", "contract_version": 1, "created_at": "2026-11-02T10:00:00Z", "created_by_user_id": "00000000-0000-4000-8000-000000000002", "disclosure": "This model runs on the laboratory CPU host.", "effective_inputs": { "value": 2 }, "execution_control": { "authorization_reason": null, "state": "authorized" }, "execution_location": "Approved laboratory CPU host", "last_observed_at": null, "model_id": "scalar-double", "observation_freshness": "unknown", "phase": null, "publication_id": "scalar-double-r1", "purpose": "standard", "requested_inputs": { "value": 2 }, "resolution": null, "result": null, "run_id": "00000000-0000-4000-8000-000000000001", "state": "queued" } }, "running-run": { "description": "One accepted scalar run, followed through coherent queued, running and terminal observations. Replay returns the original queued receipt, not the current inspection.", "summary": "running-run", "value": { "blocked_reason": null, "cancellation": null, "cancelled_at": null, "context_id": "lab-cpu", "contract_version": 1, "created_at": "2026-11-02T10:00:00Z", "created_by_user_id": "00000000-0000-4000-8000-000000000002", "disclosure": "This model runs on the laboratory CPU host.", "effective_inputs": { "value": 2 }, "execution_control": { "authorization_reason": null, "state": "authorized" }, "execution_location": "Approved laboratory CPU host", "last_observed_at": "2026-11-02T10:01:00Z", "model_id": "scalar-double", "observation_freshness": "fresh", "phase": "executing", "publication_id": "scalar-double-r1", "purpose": "standard", "requested_inputs": { "value": 2 }, "resolution": null, "result": null, "run_id": "00000000-0000-4000-8000-000000000001", "state": "running" } }, "succeeded-run": { "description": "One accepted scalar run, followed through coherent queued, running and terminal observations. Replay returns the original queued receipt, not the current inspection.", "summary": "succeeded-run", "value": { "blocked_reason": null, "cancellation": null, "cancelled_at": null, "context_id": "lab-cpu", "contract_version": 1, "created_at": "2026-11-02T10:00:00Z", "created_by_user_id": "00000000-0000-4000-8000-000000000002", "disclosure": "This model runs on the laboratory CPU host.", "effective_inputs": { "value": 2 }, "execution_control": { "authorization_reason": null, "state": "completed" }, "execution_location": "Approved laboratory CPU host", "last_observed_at": "2026-11-02T10:01:00Z", "model_id": "scalar-double", "observation_freshness": "fresh", "phase": null, "publication_id": "scalar-double-r1", "purpose": "standard", "requested_inputs": { "value": 2 }, "resolution": null, "result": { "failure": null, "files": {}, "optional_output_failures": {}, "outputs": { "doubled": 4 }, "receipt": { "assignment_id": "00000000-0000-4000-8000-000000000003", "attempt_id": "00000000-0000-4000-8000-000000000004", "completed_at": "2026-11-02T10:01:00Z", "outcome": "succeeded", "run_id": "00000000-0000-4000-8000-000000000001" } }, "run_id": "00000000-0000-4000-8000-000000000001", "state": "succeeded" } } }, "schema": { "$ref": "#/components/schemas/RunDetail" } } }, "description": "Accepted inputs, immutable requirements and current public state for the submitter or current model owner/co-admin, using these same routes. No query parameters are accepted.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Run detail does not accept query parameters. Code bad_request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An active user credential is required. Code unauthenticated.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Run identity is invalid, absent or unauthorized. Submitters and current model owners/co-admins may inspect. Code not_found.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication or run inspection is temporarily unavailable. Code run_inspection_unavailable for inspection failures.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Runs" ], "x-enumeray-contract": { "errors": [ "403 insufficient_scope", "404 not_found: missing or unauthorized resource" ], "guards": "No mutation or execution authority is granted.", "method": "get", "next_action": "Inspect current state; follow exact referenced artifact identities.", "path": "/api/v1/runs/{run_id}", "purpose": "Inspect accepted inputs, immutable requirements and current run state.", "retained": "Run identity; opaque cursor where returned.", "retry": "Repeat GET using the same resource identity; each request rechecks current credential and resource authority.", "roles": "Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.", "scopes": [ "runs:read" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/runs/{run_id}/artifacts": { "get": { "description": "List scientific output artifacts; input artifacts and log archives are separate.\n\n**Credential scopes:** `artifacts:read`\n\n**Resource authority:** Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.\n\n**Retry:** Repeat GET using the same resource identity; each request rechecks current credential and resource authority.\n\n**Guards:** No mutation or execution authority is granted.\n\n**Retain:** Run identity; opaque cursor where returned.\n\n**Specific failures:** 403 insufficient_scope; 404 not_found: missing or unauthorized resource\n\n**Next action:** Inspect current state; follow exact referenced artifact identities. [Worked workflow](/reference/http-workflows/)", "operationId": "list_artifacts", "parameters": [ { "description": "Producing run readable by its submitter or current model administrator.", "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Maximum summaries per page.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque continuation bound to the creator and producing run.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 1024, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactList" } } }, "description": "Bounded output summaries ordered by artifact UUID ascending. Empty for a run with no outputs; includes all availability states. Live pagination, not a snapshot.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid pagination. Unknown and duplicate parameters are rejected.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active user credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid, unknown or unauthorized run, checked before pagination.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Artifact records unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Artifacts" ], "x-enumeray-contract": { "errors": [ "403 insufficient_scope", "404 not_found: missing or unauthorized resource" ], "guards": "No mutation or execution authority is granted.", "method": "get", "next_action": "Inspect current state; follow exact referenced artifact identities.", "path": "/api/v1/runs/{run_id}/artifacts", "purpose": "List scientific output artifacts; input artifacts and log archives are separate.", "retained": "Run identity; opaque cursor where returned.", "retry": "Repeat GET using the same resource identity; each request rechecks current credential and resource authority.", "roles": "Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.", "scopes": [ "artifacts:read" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/runs/{run_id}/cancellation": { "put": { "description": "Request cancellation of this creator's queued or assigned run. Send an empty body; no query parameters or idempotency key are required. Repeating the PUT preserves the original intent and returns its current status. Assigned work records intent until termination is confirmed.", "operationId": "cancel_run", "parameters": [ { "description": "Accepted run identity.", "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancellationReceipt" } } }, "description": "Durable cancellation intent and current confirmation status.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The request has query parameters or a nonempty body. Code bad_request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An active user credential is required. Code unauthenticated.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Run identity is invalid, absent, or belongs to another creator. Code not_found.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The run completed before the request or its backend does not support cancellation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication/cancellation is unavailable, or its commit acknowledgement is uncertain. Code cancellation_uncertain requires retrying the same PUT.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Runs" ] } }, "/api/v1/runs/{run_id}/events": { "get": { "description": "Read retained observations and diagnostics.\n\n**Credential scopes:** `runs:read`\n\n**Resource authority:** Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.\n\n**Retry:** Repeat GET using the same resource identity; each request rechecks current credential and resource authority.\n\n**Guards:** No mutation or execution authority is granted.\n\n**Retain:** Run identity; opaque cursor where returned.\n\n**Specific failures:** 403 insufficient_scope; 404 not_found: missing or unauthorized resource\n\n**Next action:** Inspect current state; follow exact referenced artifact identities. [Worked workflow](/reference/http-workflows/)\n\nAuthorized bounded observation and diagnostic history for the submitter or current model owner/co-admin ordered by durable arrival position, including stale observations and completed runs. Existing immutable event requests and receipts do not expire. Diagnostics never become logs or terminal results implicitly.", "operationId": "get_events", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Maximum entries per page, ascending by durable acceptance position.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque exclusive boundary scoped to creator, run, and history kind.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 1024, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventHistory" } } }, "description": "Bounded immutable event evidence and continuation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid pagination or cursor scope.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active user credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Run absent or unauthorized; current model-administrator reads are audited.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "History temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Runs" ], "x-enumeray-contract": { "errors": [ "403 insufficient_scope", "404 not_found: missing or unauthorized resource" ], "guards": "No mutation or execution authority is granted.", "method": "get", "next_action": "Inspect current state; follow exact referenced artifact identities.", "path": "/api/v1/runs/{run_id}/events", "purpose": "Read retained observations and diagnostics.", "retained": "Run identity; opaque cursor where returned.", "retry": "Repeat GET using the same resource identity; each request rechecks current credential and resource authority.", "roles": "Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.", "scopes": [ "runs:read" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/runs/{run_id}/log-archive": { "get": { "description": "Inspect the separate diagnostic archive and its availability.\n\n**Credential scopes:** `runs:read`\n\n**Resource authority:** Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.\n\n**Retry:** Repeat GET using the same resource identity; each request rechecks current credential and resource authority.\n\n**Guards:** No mutation or execution authority is granted.\n\n**Retain:** Run identity; opaque cursor where returned.\n\n**Specific failures:** 403 insufficient_scope; 404 not_found: missing or unauthorized resource\n\n**Next action:** Inspect current state; follow exact referenced artifact identities. [Worked workflow](/reference/http-workflows/)", "operationId": "get_archive", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogArchiveStatus" } } }, "description": "Independent publication, completeness and expiry status; download ready bytes with the ordinary artifact endpoint.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown or unauthorized run.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Runs" ], "x-enumeray-contract": { "errors": [ "403 insufficient_scope", "404 not_found: missing or unauthorized resource" ], "guards": "No mutation or execution authority is granted.", "method": "get", "next_action": "Inspect current state; follow exact referenced artifact identities.", "path": "/api/v1/runs/{run_id}/log-archive", "purpose": "Inspect the separate diagnostic archive and its availability.", "retained": "Run identity; opaque cursor where returned.", "retry": "Repeat GET using the same resource identity; each request rechecks current credential and resource authority.", "roles": "Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.", "scopes": [ "runs:read" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/runs/{run_id}/logs": { "get": { "description": "Read retained log batches in arrival order.\n\n**Credential scopes:** `runs:read`\n\n**Resource authority:** Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.\n\n**Retry:** Repeat GET using the same resource identity; each request rechecks current credential and resource authority.\n\n**Guards:** No mutation or execution authority is granted.\n\n**Retain:** Run identity; opaque cursor where returned.\n\n**Specific failures:** 403 insufficient_scope; 404 not_found: missing or unauthorized resource\n\n**Next action:** Inspect current state; follow exact referenced artifact identities. [Worked workflow](/reference/http-workflows/)\n\nAuthorized ascending retained log batches for the submitter or current model owner/co-admin, including completed runs. Each run retains at most 1024 batches for at most seven days. Read and ingestion prune expired payloads without erasing ingestion acknowledgements. Source gaps and source_reset mark missing source bytes. A nonzero retention prefix marks expired API payloads. resume_cursor permits subsequent polling or SSE even when a page is empty.", "operationId": "get_logs", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Maximum entries per page, ascending by durable acceptance position.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque exclusive boundary scoped to creator, run, and history kind.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 1024, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogHistory" } } }, "description": "Bounded retained payloads and recovery boundary.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid, duplicate, unknown, wrong-scope, or future cursor/limit. Code invalid_pagination.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active user credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Run absent or unauthorized; current model-administrator reads are audited.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "history_cursor_expired; use X-History-Recovery-Cursor to resume and display the omitted prefix.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "X-History-Earliest-Position": { "description": "Earliest retained position, absent if empty.", "schema": { "format": "int64", "type": "integer" } }, "X-History-Latest-Position": { "description": "Latest ever accepted position.", "schema": { "format": "int64", "type": "integer" } }, "X-History-Recovery-Cursor": { "description": "Opaque cursor before earliest retained entry, or at latest consumed position if none remain.", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "History temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Runs" ], "x-enumeray-contract": { "errors": [ "403 insufficient_scope", "404 not_found: missing or unauthorized resource" ], "guards": "No mutation or execution authority is granted.", "method": "get", "next_action": "Inspect current state; follow exact referenced artifact identities.", "path": "/api/v1/runs/{run_id}/logs", "purpose": "Read retained log batches in arrival order.", "retained": "Run identity; opaque cursor where returned.", "retry": "Repeat GET using the same resource identity; each request rechecks current credential and resource authority.", "roles": "Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.", "scopes": [ "runs:read" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/runs/{run_id}/logs/stream": { "get": { "description": "Follow retained and live logs without treating stream closure as run completion.\n\n**Credential scopes:** `runs:read`\n\n**Resource authority:** Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.\n\n**Retry:** Reconnect with either the saved Last-Event-ID or cursor, never both.\n\n**Guards:** Credential and current model membership are rechecked before each buffered entry and idle poll.\n\n**Retain:** Run identity and last delivered cursor; on retention gaps, recovery cursor.\n\n**Specific failures:** 403 insufficient_scope; 404 not_found; 410 history_cursor_expired; auth_revoked stream event\n\n**Next action:** Poll run inspection independently; show retention gaps when resuming. [Worked workflow](/reference/http-workflows/)\n\nResume logs as the submitter or current model owner/co-admin from Last-Event-ID or cursor. Each log event has an opaque cursor ID. Durable polling joins replay and live delivery without a notification race. At most 32 entries are buffered; 128 streams per application are admitted. Credentials and current resource membership are rechecked before each buffered entry and idle poll. Keepalive comments arrive every 15 seconds. retention_gap supplies a recovery cursor; auth_revoked, source_unavailable and shutdown close the response. Silence or stream closure never establishes run completion.", "operationId": "stream_logs", "parameters": [ { "description": "Run readable by its submitter or current model owner/co-admin.", "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "A log history resume cursor. Mutually exclusive with Last-Event-ID.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Resume strictly after this log cursor.", "in": "header", "name": "Last-Event-ID", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } } }, "description": "SSE log events with cursor IDs and bounded control events.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid, duplicate, conflicting or wrong-scope cursor.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active user credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Run absent or unauthorized.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "history_cursor_expired. Resume with X-History-Recovery-Cursor and display the omitted prefix.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "X-History-Earliest-Position": { "description": "Earliest retained position, absent when empty.", "schema": { "format": "int64", "type": "integer" } }, "X-History-Latest-Position": { "description": "Latest ever accepted position.", "schema": { "format": "int64", "type": "integer" } }, "X-History-Recovery-Cursor": { "description": "Cursor immediately before retained logs, or latest consumed position if empty.", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "All 128 stream slots are in use. Retry later.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication or retained logs unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Logs" ], "x-enumeray-contract": { "errors": [ "403 insufficient_scope", "404 not_found", "410 history_cursor_expired", "auth_revoked stream event" ], "guards": "Credential and current model membership are rechecked before each buffered entry and idle poll.", "method": "get", "next_action": "Poll run inspection independently; show retention gaps when resuming.", "path": "/api/v1/runs/{run_id}/logs/stream", "purpose": "Follow retained and live logs without treating stream closure as run completion.", "retained": "Run identity and last delivered cursor; on retention gaps, recovery cursor.", "retry": "Reconnect with either the saved Last-Event-ID or cursor, never both.", "roles": "Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.", "scopes": [ "runs:read" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/runs/{run_id}/provenance": { "get": { "description": "Inspect a consistent versioned snapshot of recorded run evidence.\n\n**Credential scopes:** `runs:read`\n\n**Resource authority:** Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.\n\n**Retry:** Repeat GET using the same resource identity; each request rechecks current credential and resource authority.\n\n**Guards:** No mutation or execution authority is granted.\n\n**Retain:** Run identity; opaque cursor where returned.\n\n**Specific failures:** 403 insufficient_scope; 404 not_found: missing or unauthorized resource\n\n**Next action:** Inspect current state; follow exact referenced artifact identities. [Worked workflow](/reference/http-workflows/)\n\nA consistent snapshot of recorded acceptance, scientific definition, execution receipts, exact verified input/output versions and direct upstream producers. In-progress runs accumulate evidence. Contains no storage locators, credentials or temporary transfer authorization. The submitter retains historical access after model-grant revocation. Current model owners/co-admins may read with an audit record; removing that administrative membership removes its read authority. Historical storage availability does not govern metadata retrieval.", "operationId": "get_provenance", "parameters": [ { "description": "Run identity readable by its submitter or current model owner/co-admin.", "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunProvenance" } } }, "description": "Version-1 provenance JSON; deterministic while recorded facts are unchanged.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Query parameters are not accepted.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active user credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid, unknown or unauthorized run.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Provenance records unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Runs" ], "x-enumeray-contract": { "errors": [ "403 insufficient_scope", "404 not_found: missing or unauthorized resource" ], "guards": "No mutation or execution authority is granted.", "method": "get", "next_action": "Inspect current state; follow exact referenced artifact identities.", "path": "/api/v1/runs/{run_id}/provenance", "purpose": "Inspect a consistent versioned snapshot of recorded run evidence.", "retained": "Run identity; opaque cursor where returned.", "retry": "Repeat GET using the same resource identity; each request rechecks current credential and resource authority.", "roles": "Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.", "scopes": [ "runs:read" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/runs/{run_id}/provenance/content": { "get": { "description": "Download the same recorded provenance as a JSON attachment.\n\n**Credential scopes:** `runs:read`\n\n**Resource authority:** Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.\n\n**Retry:** Repeat GET using the same resource identity; each request rechecks current credential and resource authority.\n\n**Guards:** No mutation or execution authority is granted.\n\n**Retain:** Run identity; opaque cursor where returned.\n\n**Specific failures:** 403 insufficient_scope; 404 not_found: missing or unauthorized resource\n\n**Next action:** Inspect current state; follow exact referenced artifact identities. [Worked workflow](/reference/http-workflows/)\n\nDownload the same versioned provenance document as an application/json attachment. Generated directly from a consistent durable metadata snapshot, with no object-storage dependency or temporary URL. This derived export does not allocate an output artifact or change the run. HEAD returns the same headers with no body.", "operationId": "get_provenance_content", "parameters": [ { "description": "Run identity readable by its submitter or current model owner/co-admin.", "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunProvenance" } } }, "description": "Downloadable provenance JSON artifact.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "Content-Disposition": { "description": "attachment; filename=run-{run_id}-provenance.json", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Query parameters are not accepted.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active user credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid, unknown or unauthorized run.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Provenance records unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Runs" ], "x-enumeray-contract": { "errors": [ "403 insufficient_scope", "404 not_found: missing or unauthorized resource" ], "guards": "No mutation or execution authority is granted.", "method": "get", "next_action": "Inspect current state; follow exact referenced artifact identities.", "path": "/api/v1/runs/{run_id}/provenance/content", "purpose": "Download the same recorded provenance as a JSON attachment.", "retained": "Run identity; opaque cursor where returned.", "retry": "Repeat GET using the same resource identity; each request rechecks current credential and resource authority.", "roles": "Run submitter or current model owner/co-admin; model-administrator reads are audited. Connector administration and model execution grants alone confer no scientific read access.", "scopes": [ "runs:read" ], "workflow": "/reference/http-workflows/" } } }, "/api/v1/tokens": { "get": { "description": "List the authenticated account's personal token metadata; default page size 50, maximum 100.\n\n**Credential scopes:** `tokens:manage`\n\n**Resource authority:** Authenticated account manages its own personal credentials; no model-user or connector role is required.\n\n**Retry:** Repeat inventory GET safely. Token issuance is not an idempotent reservation; after uncertainty inspect inventory before issuing another token.\n\n**Guards:** Requested scopes cannot exceed parent scopes and expiration cannot exceed parent lifetime.\n\n**Retain:** Account, token ID/name/scopes and inventory cursor; token secret is returned only at issuance.\n\n**Specific failures:** 403 insufficient_scope or scope_escalation; 422 invalid_token_request\n\n**Next action:** Save issued secret privately; inventory never reveals it. [Worked workflow](/start/login/)", "operationId": "selfservice_get_api_v1_tokens", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Continuation from next_cursor; management collections also accept after.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "empty-token-inventory": { "description": "Inventory never returns a secret. Issuance returns the secret only once. Values are inert fixtures.", "summary": "empty-token-inventory", "value": { "items": [], "next_cursor": null } }, "token-inventory": { "description": "Inventory never returns a secret. Issuance returns the secret only once. Values are inert fixtures.", "summary": "token-inventory", "value": { "items": [ { "created_at": "2026-11-02T10:00:00Z", "expires_at": "2026-11-03T10:00:00Z", "id": "00000000-0000-4000-8000-000000000010", "name": "analysis-script", "revoked_at": null, "scopes": [ "models:read", "runs:read" ] }, { "created_at": "2026-11-02T10:00:00Z", "expires_at": null, "id": "00000000-0000-4000-8000-000000000015", "name": "operator-issued", "revoked_at": null, "scopes": [ "*" ] } ], "next_cursor": null } } }, "schema": { "$ref": "#/components/schemas/TokenPage" } } }, "description": "List the caller's personal tokens without secrets.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "List the caller's personal tokens without secrets.", "tags": [ "Self service" ], "x-enumeray-contract": { "errors": [ "403 insufficient_scope or scope_escalation", "422 invalid_token_request" ], "guards": "Requested scopes cannot exceed parent scopes and expiration cannot exceed parent lifetime.", "method": "get", "next_action": "Save issued secret privately; inventory never reveals it.", "path": "/api/v1/tokens", "purpose": "List the authenticated account's personal token metadata; default page size 50, maximum 100.", "retained": "Account, token ID/name/scopes and inventory cursor; token secret is returned only at issuance.", "retry": "Repeat inventory GET safely. Token issuance is not an idempotent reservation; after uncertainty inspect inventory before issuing another token.", "roles": "Authenticated account manages its own personal credentials; no model-user or connector role is required.", "scopes": [ "tokens:manage" ], "workflow": "/start/login/" } }, "post": { "description": "Issue a bounded personal token once; store its returned secret privately.\n\n**Credential scopes:** `tokens:manage`\n\n**Resource authority:** Authenticated account manages its own personal credentials; no model-user or connector role is required.\n\n**Retry:** Repeat inventory GET safely. Token issuance is not an idempotent reservation; after uncertainty inspect inventory before issuing another token.\n\n**Guards:** Requested scopes cannot exceed parent scopes and expiration cannot exceed parent lifetime.\n\n**Retain:** Account, token ID/name/scopes and inventory cursor; token secret is returned only at issuance.\n\n**Specific failures:** 403 insufficient_scope or scope_escalation; 422 invalid_token_request\n\n**Next action:** Save issued secret privately; inventory never reveals it. [Worked workflow](/start/login/)", "operationId": "selfservice_post_api_v1_tokens", "requestBody": { "content": { "application/json": { "examples": { "issue-token": { "description": "Inventory never returns a secret. Issuance returns the secret only once. Values are inert fixtures.", "summary": "issue-token", "value": { "expires_in_seconds": 86400, "name": "analysis-script", "scopes": [ "models:read", "runs:read" ] } } }, "schema": { "$ref": "#/components/schemas/CreateToken" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "issue-token": { "description": "Inventory never returns a secret. Issuance returns the secret only once. Values are inert fixtures.", "summary": "issue-token", "value": { "expires_at": "2026-11-03T10:00:00Z", "id": "00000000-0000-4000-8000-000000000010", "scopes": [ "models:read", "runs:read" ], "token": "fixture-only-not-a-credential", "user_id": "00000000-0000-4000-8000-000000000002" } } }, "schema": { "$ref": "#/components/schemas/TokenIssued" } } }, "description": "Create a scoped expiring personal token; scopes never replace resource authorization.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Create a scoped expiring personal token; scopes never replace resource authorization.", "tags": [ "Self service" ], "x-enumeray-contract": { "errors": [ "403 insufficient_scope or scope_escalation", "422 invalid_token_request" ], "guards": "Requested scopes cannot exceed parent scopes and expiration cannot exceed parent lifetime.", "method": "post", "next_action": "Save issued secret privately; inventory never reveals it.", "path": "/api/v1/tokens", "purpose": "Issue a bounded personal token once; store its returned secret privately.", "retained": "Account, token ID/name/scopes and inventory cursor; token secret is returned only at issuance.", "retry": "Repeat inventory GET safely. Token issuance is not an idempotent reservation; after uncertainty inspect inventory before issuing another token.", "roles": "Authenticated account manages its own personal credentials; no model-user or connector role is required.", "scopes": [ "tokens:manage" ], "workflow": "/start/login/" } } }, "/api/v1/tokens/{token_id}": { "delete": { "operationId": "selfservice_delete_api_v1_tokens__token_id_", "parameters": [ { "in": "path", "name": "token_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Revoke the caller's personal token.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "summary": "Revoke the caller's personal token.", "tags": [ "Self service" ] } }, "/api/v1/uploads": { "post": { "description": "Reserve exact bytes with durable upload and artifact identities.\n\n**Credential scopes:** `uploads:create`\n\n**Resource authority:** Authenticated creator; private reservation ownership does not grant model or connector authority.\n\n**Retry:** Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.\n\n**Guards:** New reservations select multipart strictly above 64 MiB. Single-PUT ceiling, per-file policy, declaration and aggregate quotas are independent. Existing reservations retain transport and expiry.\n\n**Retain:** Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.\n\n**Specific failures:** 400 invalid_idempotency_key; 409 idempotency_conflict; 413 metadata/body or general structural byte bound; 422 invalid_upload; 429 upload_quota_exceeded; 503 upload_uncertain\n\n**Next action:** Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification. [Worked workflow](/users/files/)", "operationId": "user_create_upload", "parameters": [ { "description": "Required once; 1–128 ASCII letters, digits, underscores or hyphens. Keep the same key/request after a lost response. Successful keys never expire.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadRequest" } } }, "description": "A bounded description, expected byte length and canonical full-object SHA-256. Ownership, destination, keys and expiry are service-selected. No query parameters.", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadView" } } }, "description": "Durable reservation. Equivalent retries keep the original reservation receipt; current state and temporary transfer instructions are fresh. A storage outage returns transfer.status=unavailable without losing the reservation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "Location": { "description": "/api/v1/uploads/{upload_id}", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON, query parameters, or invalid/repeated/missing idempotency key.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active user credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The same user/key has different semantic request content (idempotency_conflict).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request exceeds 64 KiB or the file exceeds the structural transport limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "JSON content type required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid description, metadata, checksum, unsupported or duplicate fields.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "File admission or active transfer quota exhausted; keep the original operation and retry after capacity is reclaimed.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upload operation unavailable, storage not configured, or upload_uncertain: retry the same key and request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Uploads" ], "x-enumeray-contract": { "errors": [ "400 invalid_idempotency_key", "409 idempotency_conflict", "413 metadata/body or general structural byte bound", "422 invalid_upload", "429 upload_quota_exceeded", "503 upload_uncertain" ], "guards": "New reservations select multipart strictly above 64 MiB. Single-PUT ceiling, per-file policy, declaration and aggregate quotas are independent. Existing reservations retain transport and expiry.", "method": "post", "next_action": "Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification.", "path": "/api/v1/uploads", "purpose": "Reserve exact bytes with durable upload and artifact identities.", "retained": "Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.", "retry": "Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.", "roles": "Authenticated creator; private reservation ownership does not grant model or connector authority.", "scopes": [ "uploads:create" ], "workflow": "/users/files/" } } }, "/api/v1/uploads/{upload_id}": { "get": { "description": "Inspect the original reservation and refresh temporary transfer instructions.\n\n**Credential scopes:** `uploads:read`\n\n**Resource authority:** Authenticated creator; private reservation ownership does not grant model or connector authority.\n\n**Retry:** Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.\n\n**Guards:** New reservations select multipart strictly above 64 MiB. Single-PUT ceiling, per-file policy, declaration and aggregate quotas are independent. Existing reservations retain transport and expiry.\n\n**Retain:** Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.\n\n**Specific failures:** 400 bad_request; 404 not_found: missing or unauthorized upload; 503 upload_unavailable\n\n**Next action:** Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification. [Worked workflow](/users/files/)", "operationId": "user_read_upload", "parameters": [ { "description": "Creator-owned upload reservation.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadView" } } }, "description": "Current pending/expired/completed state. Pending uploads can receive renewed PUT instructions. Completed uploads include their immutable completion receipt and issue no further transfer authority; expired uploads remain inspectable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid path or query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active user credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unknown and other-user upload IDs are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upload status could not be read before its deadline.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Uploads" ], "x-enumeray-contract": { "errors": [ "400 bad_request", "404 not_found: missing or unauthorized upload", "503 upload_unavailable" ], "guards": "New reservations select multipart strictly above 64 MiB. Single-PUT ceiling, per-file policy, declaration and aggregate quotas are independent. Existing reservations retain transport and expiry.", "method": "get", "next_action": "Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification.", "path": "/api/v1/uploads/{upload_id}", "purpose": "Inspect the original reservation and refresh temporary transfer instructions.", "retained": "Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.", "retry": "Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.", "roles": "Authenticated creator; private reservation ownership does not grant model or connector authority.", "scopes": [ "uploads:read" ], "workflow": "/users/files/" } } }, "/api/v1/uploads/{upload_id}/completion": { "put": { "description": "Verify and publish the exact stored version; multipart may return 202 while the worker verifies.\n\n**Credential scopes:** `uploads:complete`\n\n**Resource authority:** Authenticated creator; private reservation ownership does not grant model or connector authority.\n\n**Retry:** Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.\n\n**Guards:** New reservations select multipart strictly above 64 MiB. Single-PUT ceiling, per-file policy, declaration and aggregate quotas are independent. Existing reservations retain transport and expiry.\n\n**Retain:** Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.\n\n**Specific failures:** 400 bad_request; 404 not_found: missing or unauthorized upload; 409 upload_bytes_missing or upload_completion_conflict; 410 upload_expired; 413 completion JSON/body bound; 422 invalid_upload_completion or upload_verification_failed; 503 upload_uncertain\n\n**Next action:** Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification. [Worked workflow](/users/files/)", "operationId": "user_complete_upload", "parameters": [ { "description": "Creator-owned upload reservation.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionBody" } } }, "description": "For single PUT use the non-null version_id returned by storage. For multipart use {multipart:true}; retry unchanged while HTTP 202 is returned. At most 8 KiB; no unknown/duplicate fields or query parameters. Save this request and retry it unchanged after a lost response. No additional idempotency key is needed.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadCompletionReceipt" } } }, "description": "Verified exact version published atomically. Identical retries return the original receipt, including after expiry or later storage unavailability, without republishing bytes. Downloads and file-input authorization are separate features.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Progress" } } }, "description": "Multipart assembly or exact-version verification is pending; retry the same multipart completion intent.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON, path or query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active user credential required, rechecked before publication.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unknown and other-user uploads are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "upload_bytes_missing: storage reported no such version; or upload_completion_conflict: a different version was already published.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "upload_expired: unpublished reservation expired before publication.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Completion JSON exceeds 8 KiB or the deployment limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "JSON content type required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid completion request, or upload_verification_failed: exact-version metadata, byte size or native full-object SHA-256 differs or is absent.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Storage/database unavailable or upload_uncertain. Preserve and retry the same version request; inspect status to reconcile publication.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Uploads" ], "x-enumeray-contract": { "errors": [ "400 bad_request", "404 not_found: missing or unauthorized upload", "409 upload_bytes_missing or upload_completion_conflict", "410 upload_expired", "413 completion JSON/body bound", "422 invalid_upload_completion or upload_verification_failed", "503 upload_uncertain" ], "guards": "New reservations select multipart strictly above 64 MiB. Single-PUT ceiling, per-file policy, declaration and aggregate quotas are independent. Existing reservations retain transport and expiry.", "method": "put", "next_action": "Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification.", "path": "/api/v1/uploads/{upload_id}/completion", "purpose": "Verify and publish the exact stored version; multipart may return 202 while the worker verifies.", "retained": "Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.", "retry": "Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.", "roles": "Authenticated creator; private reservation ownership does not grant model or connector authority.", "scopes": [ "uploads:complete" ], "workflow": "/users/files/" } } }, "/api/v1/uploads/{upload_id}/multipart": { "delete": { "operationId": "user_abort", "parameters": [ { "description": "Private upload reservation.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "202": { "description": "Transport initialization or verification is pending.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "204": { "description": "Checked multipart operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Part or lifecycle conflicts.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "description": "Reservation expired.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid part or integrity mismatch.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Retry the same operation after storage recovery.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Uploads" ] } }, "/api/v1/uploads/{upload_id}/parts": { "get": { "operationId": "user_parts", "parameters": [ { "description": "Private upload reservation.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Exclusive part cursor; at most 100 descriptions per page.", "in": "query", "name": "after", "required": false, "schema": { "format": "int32", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartPage" } } }, "description": "Checked multipart operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "202": { "description": "Transport initialization or verification is pending.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Part or lifecycle conflicts.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "description": "Reservation expired.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid part or integrity mismatch.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Retry the same operation after storage recovery.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Uploads" ] } }, "/api/v1/uploads/{upload_id}/parts/{part_number}": { "put": { "operationId": "user_authorize", "parameters": [ { "description": "Private upload reservation.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "One-based immutable part number.", "in": "path", "name": "part_number", "required": true, "schema": { "format": "int32", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartRequest" } } }, "description": "Immutable full-part SHA-256. Service derives exact size and offset; repeated identical requests refresh authorization.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartAuthorization" } } }, "description": "Checked multipart operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "202": { "description": "Transport initialization or verification is pending.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Part or lifecycle conflicts.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "description": "Reservation expired.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid part or integrity mismatch.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Retry the same operation after storage recovery.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Uploads" ] } }, "/api/v1/uploads/{upload_id}/parts/{part_number}/receipt": { "put": { "operationId": "user_ack", "parameters": [ { "description": "Private upload reservation.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "One-based immutable part number.", "in": "path", "name": "part_number", "required": true, "schema": { "format": "int32", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartView" } } }, "description": "Checked multipart operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "202": { "description": "Transport initialization or verification is pending.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The credential does not permit this operation (insufficient_scope).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Part or lifecycle conflicts.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "description": "Reservation expired.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid part or integrity mismatch.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Retry the same operation after storage recovery.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "user_bearer": [] } ], "tags": [ "Uploads" ] } }, "/connector/v1/assignments": { "get": { "description": "Read this connector's outstanding assignments for reconciliation, ordered by creation time and identity, oldest first. This is a live inventory, not a snapshot. An active process session is not required. Retrieving work never authorizes another backend submission or execution attempt.", "operationId": "list_assignments", "parameters": [ { "description": "Maximum summaries per page; specifications are fetched separately.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque continuation scoped to this connector's outstanding inventory.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 2048, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentList" } } }, "description": "Bounded summaries of running assignments and terminal assignments awaiting delivery settlement. Revocations, stale heartbeats, and released sessions do not hide existing work.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid, unknown, duplicate, or incompatible pagination parameters. Code invalid_pagination.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active connector credential required, rechecked while holding the connector lock.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Assignment inspection is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] }, "post": { "operationId": "claim", "parameters": [ { "description": "Required once; connector-scoped, retained only when an assignment is created. Empty polls leave the key unused.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+$", "type": "string" } }, { "description": "Active process ownership session. Session changes do not change claim semantics.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimRequest" } } }, "description": "Empty JSON object. FIFO eligibility is server-selected. Unknown fields and query parameters are rejected; 8 KiB maximum body.", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentReceipt" } } }, "description": "Assignment and running/preparing transition committed. Repeating a successful key returns the original immutable specification.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "Location": { "description": "Assignment detail with the pinned receipt and current state.", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "204": { "description": "No eligible work or outstanding-work allowance. No durable key is consumed.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "Retry-After": { "description": "1 second; use bounded polling.", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON, query parameters, invalid Idempotency-Key or X-Connector-Session header.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connector credential, including a write-time revocation check.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An active owned session is required (session_required).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Body exceeds the 8 KiB or configured limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "JSON content type required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Claim body must be an empty JSON object.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Coordination unavailable or commit uncertain. Retry the same key; never infer that an assignment did not commit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment_id}": { "get": { "description": "Retrieve retained work already assigned to this connector, without requiring an active session. The original immutable receipt is separate from current public progress. This read does not grant permission to launch or relaunch the work.", "operationId": "get_assignment", "parameters": [ { "description": "Existing assignment identity.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentDetail" } } }, "description": "Original pinned assignment and current state, including after publication or installation revocation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Query parameters are not accepted. Code bad_request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active connector credential required, rechecked while holding the connector lock.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Assignment identity is invalid, absent, or belongs to another connector. Code not_found.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Assignment inspection is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment_id}/artifacts/{artifact_id}": { "get": { "description": "Only artifacts produced by this exact assignment or pinned as its accepted inputs are accessible. The assignment must belong to the authenticated connector. Existing delegation survives session release and later installation/publication revocation. Only schema-declared file inputs create dependency pins; arbitrary input JSON confers no access.", "operationId": "connector_artifact", "parameters": [ { "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "artifact_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactDetail" } } }, "description": "Metadata for this assignment's output or pinned input artifact.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Query parameters are not accepted.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active connector credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid identity or artifact outside this exact owned assignment.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Artifact records unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Artifacts" ] } }, "/connector/v1/assignments/{assignment_id}/artifacts/{artifact_id}/content": { "get": { "description": "Same exact-version, five-minute download contract as user content. Only an exact owned producing assignment or accepted input dependency confers access; arbitrary inputs, another assignment and compute grants do not. Credential and availability are rechecked after storage verification. No active process session is required.", "operationId": "connector_content", "parameters": [ { "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "artifact_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "303": { "description": "Temporary GET capability. Follow without API authorization headers; never log the URL.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "Location": { "description": "Secret exact-version URL, at most 300 seconds.", "schema": { "type": "string" } }, "Referrer-Policy": { "description": "no-referrer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Query parameters are not accepted.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active connector credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid identity or artifact outside this exact owned assignment.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "artifact_not_ready.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "artifact_gone.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Artifact records or exact-version storage unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Artifacts" ] } }, "/connector/v1/assignments/{assignment_id}/control": { "get": { "operationId": "selfservice_get_connector_v1_assignments__assignment_id__control", "parameters": [ { "in": "path", "name": "assignment_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentControl" } } }, "description": "Check launch permission, pending-only access revocation and durable user cancellation of pending or running work.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "summary": "Check launch permission, pending-only access revocation and durable user cancellation of pending or running work.", "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment_id}/delivery": { "put": { "operationId": "put_delivery", "parameters": [ { "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryCompletionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryCompletionReceipt" } } }, "description": "Original durable delivery receipt. Scientific results remain independent.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active connector credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Owned assignment not found.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Delivery unfinished, conflicting request, attempt or ownership.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid strict request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Unavailable or commit uncertain; retry the identical request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment_id}/events/{event_id}": { "put": { "description": "Persist one execution observation or diagnostic. Save the event UUID, assignment-scoped sequence and complete body before sending. Identical retries return the original immutable receipt, including after session recovery; they do not refresh observations. Lower sequences are retained as stale without changing progress. A new backward phase or conflicting identity is rejected. Neither diagnostic severity nor phase finalizes work or frees capacity.", "operationId": "put_event", "parameters": [ { "description": "Owned assignment.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Non-nil UUID retained with this assignment.", "in": "path", "name": "event_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Required active process session for the assignment's durable journal.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventRequest" } } }, "description": "Strict JSON object, at most 8 KiB or the configured limit. Positive sequence; RFC3339 observed_at with microsecond precision or coarser; phase or diagnostic required. Backend handle required beyond preparing, and allowed only with a phase. Diagnostics alone never refresh observation freshness.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventReceipt" } } }, "description": "Event and any progress committed, or identical original receipt replayed. Current progress is available through assignment detail.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON, query parameters, invalid event ID, or invalid_session_header.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active connector credential required, rechecked before persistence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Assignment invalid, absent or owned by another connector. Code not_found.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "event_conflict, attempt_conflict, backend_conflict, invalid_transition, session_required or journal_conflict.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Body exceeds the 8 KiB or configured limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "JSON content type required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unknown or duplicate fields, invalid structure, timestamp or field limits. Code invalid_request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "assignment_unavailable or assignment_uncertain. Retry identical event identity and content.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment_id}/log-archive": { "put": { "operationId": "put_intent", "parameters": [ { "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogArchiveIntent" } } }, "description": "Pin the operator policy. Finalization is immutable once supplied. A bounded diagnostic abandons optional publication without changing the scientific result.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogArchiveStatus" } } }, "description": "Durable archive intent/status.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Policy, attempt or finalization conflict.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid archive policy.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment_id}/log-archive/uploads": { "post": { "description": "Reserve exact bytes with durable upload and artifact identities.\n\n**Credential scopes:** Separate connector bearer credential and assignment/session authority.\n\n**Resource authority:** Authenticated connector owns the exact assignment, active X-Connector-Session and finalized archive intent before its independent publication deadline.\n\n**Retry:** Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.\n\n**Guards:** New reservations select multipart strictly above 64 MiB; existing reservations keep transport and expiry. Archive size must satisfy both 512 MiB structural and captured compressed-policy bounds (422 invalid_upload).\n\n**Retain:** Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.\n\n**Specific failures:** 400 invalid_idempotency_key; 409 idempotency_conflict; 413 metadata/body or general structural byte bound; 422 invalid_upload; 429 upload_quota_exceeded; 503 upload_uncertain; 404 not_found: unrelated assignment; 409 session_required, journal_conflict or invalid_transition\n\n**Next action:** Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification. [Worked workflow](/users/files/)", "operationId": "archive_create_upload", "parameters": [ { "description": "Owned assignment.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Active process session for this assignment journal.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Required once; 1–128 ASCII letters, digits, underscores or hyphens. Keep the same key/request after a lost response. Successful keys never expire.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadRequest" } } }, "description": "A bounded description, expected byte length and canonical full-object SHA-256. logical_name must be log-archive.tar.gz; application/gzip, independent archive quotas and a valid source-range manifest are required. Ownership and storage destination are inherited from the run. Publication does not finalize the run. No query parameters.", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadView" } } }, "description": "Durable reservation. Equivalent retries keep the original reservation receipt; current state and temporary transfer instructions are fresh. A storage outage returns transfer.status=unavailable without losing the reservation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "Location": { "description": "/connector/v1/assignments/{assignment_id}/log-archive/uploads/{upload_id}", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON, query parameters, or invalid/repeated/missing idempotency key.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active connector credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unknown or unrelated assignment/upload.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "idempotency_conflict, output_upload_conflict, session_required, journal_conflict or invalid_transition. New uploads require a finalized archive intent before its publication deadline; scientific completion is independent.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request JSON exceeds 64 KiB, the deployment body limit, or the general structural artifact bound. Archive compressed-policy and 512 MiB limits reject with 422 invalid_upload.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "JSON content type required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "invalid_upload: invalid archive description, media type, source-range manifest, completeness claim, or bytes above the captured compressed-policy ceiling or 512 MiB archive maximum.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upload operation unavailable, storage not configured, or upload_uncertain: retry the same key and request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ], "x-enumeray-contract": { "errors": [ "400 invalid_idempotency_key", "409 idempotency_conflict", "413 metadata/body or general structural byte bound", "422 invalid_upload", "429 upload_quota_exceeded", "503 upload_uncertain", "404 not_found: unrelated assignment", "409 session_required, journal_conflict or invalid_transition" ], "guards": "New reservations select multipart strictly above 64 MiB; existing reservations keep transport and expiry. Archive size must satisfy both 512 MiB structural and captured compressed-policy bounds (422 invalid_upload).", "method": "post", "next_action": "Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification.", "path": "/connector/v1/assignments/{assignment_id}/log-archive/uploads", "purpose": "Reserve exact bytes with durable upload and artifact identities.", "retained": "Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.", "retry": "Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.", "roles": "Authenticated connector owns the exact assignment, active X-Connector-Session and finalized archive intent before its independent publication deadline.", "scopes": [], "workflow": "/users/files/" } } }, "/connector/v1/assignments/{assignment_id}/log-archive/uploads/{upload_id}": { "get": { "description": "Inspect the original reservation and refresh temporary transfer instructions.\n\n**Credential scopes:** Separate connector bearer credential and assignment/session authority.\n\n**Resource authority:** Authenticated connector owns the exact assignment, active X-Connector-Session and finalized archive intent before its independent publication deadline.\n\n**Retry:** Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.\n\n**Guards:** New reservations select multipart strictly above 64 MiB; existing reservations keep transport and expiry. Archive size must satisfy both 512 MiB structural and captured compressed-policy bounds (422 invalid_upload).\n\n**Retain:** Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.\n\n**Specific failures:** 400 bad_request; 404 not_found: missing or unauthorized upload; 503 upload_unavailable; 409 session_required or journal_conflict\n\n**Next action:** Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification. [Worked workflow](/users/files/)", "operationId": "archive_read_upload", "parameters": [ { "description": "Owned assignment.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Active process session for this assignment journal.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Upload reserved for this assignment.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadView" } } }, "description": "Current pending/expired/completed state. Pending archives receive renewed PUT instructions before their independent publication deadline, including after scientific completion. Completed uploads include their immutable completion receipt and issue no further transfer authority; expired uploads remain inspectable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid path or query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active connector credential and process session required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unknown and other-assignment upload IDs are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "session_required or journal_conflict.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upload status could not be read before its deadline.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ], "x-enumeray-contract": { "errors": [ "400 bad_request", "404 not_found: missing or unauthorized upload", "503 upload_unavailable", "409 session_required or journal_conflict" ], "guards": "New reservations select multipart strictly above 64 MiB; existing reservations keep transport and expiry. Archive size must satisfy both 512 MiB structural and captured compressed-policy bounds (422 invalid_upload).", "method": "get", "next_action": "Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification.", "path": "/connector/v1/assignments/{assignment_id}/log-archive/uploads/{upload_id}", "purpose": "Inspect the original reservation and refresh temporary transfer instructions.", "retained": "Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.", "retry": "Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.", "roles": "Authenticated connector owns the exact assignment, active X-Connector-Session and finalized archive intent before its independent publication deadline.", "scopes": [], "workflow": "/users/files/" } } }, "/connector/v1/assignments/{assignment_id}/log-archive/uploads/{upload_id}/completion": { "put": { "description": "Verify and publish the exact stored version; multipart may return 202 while the worker verifies.\n\n**Credential scopes:** Separate connector bearer credential and assignment/session authority.\n\n**Resource authority:** Authenticated connector owns the exact assignment, active X-Connector-Session and finalized archive intent before its independent publication deadline.\n\n**Retry:** Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.\n\n**Guards:** New reservations select multipart strictly above 64 MiB; existing reservations keep transport and expiry. Archive size must satisfy both 512 MiB structural and captured compressed-policy bounds (422 invalid_upload).\n\n**Retain:** Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.\n\n**Specific failures:** 400 bad_request; 404 not_found: missing or unauthorized upload; 409 upload_bytes_missing or upload_completion_conflict; 410 upload_expired; 413 completion JSON/body bound; 422 invalid_upload_completion or upload_verification_failed; 503 upload_uncertain; 409 session_required, journal_conflict or invalid_transition\n\n**Next action:** Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification. [Worked workflow](/users/files/)", "operationId": "archive_complete_upload", "parameters": [ { "description": "Owned assignment.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Active process session for this assignment journal.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Upload reserved for this assignment.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionBody" } } }, "description": "Single PUT uses the returned version_id; multipart uses {multipart:true}. Retry unchanged while verification is pending. At most 8 KiB; no unknown/duplicate fields or query parameters.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadCompletionReceipt" } } }, "description": "Verified exact version published atomically. Identical retries return the original receipt, including after expiry or later storage unavailability, without republishing bytes. Downloads and file-input authorization are separate features.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Progress" } } }, "description": "Multipart assembly or exact-version verification pending; repeat the same completion intent.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON, path or query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active connector credential and process session required, rechecked before publication.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unknown and other-assignment uploads are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "upload_bytes_missing: storage reported no such version; upload_completion_conflict: a different version was already published; session_required, journal_conflict or invalid_transition before publication.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "upload_expired: unpublished reservation expired before publication.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Completion JSON exceeds 8 KiB or the deployment limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "JSON content type required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid completion request, or upload_verification_failed: exact-version metadata, byte size or native full-object SHA-256 differs or is absent.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Storage/database unavailable or upload_uncertain. Preserve and retry the same version request; inspect status to reconcile publication.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ], "x-enumeray-contract": { "errors": [ "400 bad_request", "404 not_found: missing or unauthorized upload", "409 upload_bytes_missing or upload_completion_conflict", "410 upload_expired", "413 completion JSON/body bound", "422 invalid_upload_completion or upload_verification_failed", "503 upload_uncertain", "409 session_required, journal_conflict or invalid_transition" ], "guards": "New reservations select multipart strictly above 64 MiB; existing reservations keep transport and expiry. Archive size must satisfy both 512 MiB structural and captured compressed-policy bounds (422 invalid_upload).", "method": "put", "next_action": "Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification.", "path": "/connector/v1/assignments/{assignment_id}/log-archive/uploads/{upload_id}/completion", "purpose": "Verify and publish the exact stored version; multipart may return 202 while the worker verifies.", "retained": "Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.", "retry": "Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.", "roles": "Authenticated connector owns the exact assignment, active X-Connector-Session and finalized archive intent before its independent publication deadline.", "scopes": [], "workflow": "/users/files/" } } }, "/connector/v1/assignments/{assignment_id}/log-archive/uploads/{upload_id}/multipart": { "delete": { "operationId": "archive_abort", "parameters": [ { "description": "Private upload reservation.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Owned assignment.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Current process session.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "202": { "description": "Transport initialization or verification is pending.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "204": { "description": "Checked multipart operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Part or lifecycle conflicts.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "description": "Reservation expired.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid part or integrity mismatch.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Retry the same operation after storage recovery.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment_id}/log-archive/uploads/{upload_id}/parts": { "get": { "operationId": "archive_parts", "parameters": [ { "description": "Private upload reservation.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Owned assignment.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Current process session.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Exclusive part cursor; at most 100 descriptions per page.", "in": "query", "name": "after", "required": false, "schema": { "format": "int32", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartPage" } } }, "description": "Checked multipart operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "202": { "description": "Transport initialization or verification is pending.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Part or lifecycle conflicts.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "description": "Reservation expired.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid part or integrity mismatch.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Retry the same operation after storage recovery.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment_id}/log-archive/uploads/{upload_id}/parts/{part_number}": { "put": { "operationId": "archive_authorize", "parameters": [ { "description": "Private upload reservation.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Owned assignment.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Current process session.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "One-based immutable part number.", "in": "path", "name": "part_number", "required": true, "schema": { "format": "int32", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartRequest" } } }, "description": "Immutable full-part SHA-256. Service derives exact size and offset; repeated identical requests refresh authorization.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartAuthorization" } } }, "description": "Checked multipart operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "202": { "description": "Transport initialization or verification is pending.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Part or lifecycle conflicts.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "description": "Reservation expired.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid part or integrity mismatch.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Retry the same operation after storage recovery.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment_id}/log-archive/uploads/{upload_id}/parts/{part_number}/receipt": { "put": { "operationId": "archive_ack", "parameters": [ { "description": "Private upload reservation.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Owned assignment.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Current process session.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "One-based immutable part number.", "in": "path", "name": "part_number", "required": true, "schema": { "format": "int32", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartView" } } }, "description": "Checked multipart operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "202": { "description": "Transport initialization or verification is pending.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Part or lifecycle conflicts.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "description": "Reservation expired.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid part or integrity mismatch.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Retry the same operation after storage recovery.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment_id}/logs/{source}/{epoch}/{sequence}": { "put": { "description": "Persist one bounded batch, including after the scientific terminal result until durable delivery settlement. Settlement fences fresh batches while preserving verified historical replay. Save source epoch, sequence and exact body before sending. Start at epoch 1/sequence 1; continue the sequence or begin the next epoch at sequence 1. A replacement epoch produces an explicit source_reset discontinuity. Identical retries within the last 64 batches per source replay the original receipt even after payload retention; older consumed identities return log_retry_too_old and cannot insert payloads. Ingestion does not advance execution progress or release capacity.", "operationId": "put_logs", "parameters": [ { "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "source", "required": true, "schema": { "$ref": "#/components/schemas/LogSource" } }, { "in": "path", "name": "epoch", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "path", "name": "sequence", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Required active session owning the assignment journal.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogBatchRequest" } } }, "description": "Strict JSON object, at most 64 KiB or the configured limit. offset and byte_length measure raw source bytes; decoded text length never advances source progress. Text is at most 8192 UTF-8 bytes and excludes NUL. A positive gap count explains bytes omitted before offset; null counts require a reset/unavailable marker starting an epoch. Empty text requires a gap. stdout, stderr, connector, automatic slurm_batch and declared model. sources share these rules. Named sources must belong to the pinned assignment definition.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogReceipt" } } }, "description": "Durable batch receipt, or original verified replay.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid path, query or session header.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active connector credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Assignment absent or not owned by this connector.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "log_conflict, log_sequence_conflict, log_retry_too_old, invalid_transition after delivery settlement, attempt_conflict, journal_conflict, or session_required. Too-old identities are consumed, but their exact content can no longer be verified; never resend them under fresh identities.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Encoded body exceeds limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "JSON required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid structure or batch bounds.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "assignment_unavailable or assignment_uncertain. Retry the exact identity and body.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment_id}/result": { "put": { "description": "Commit a confirmed terminal outcome for this assignment. Persist the assignment identity and complete body before sending. Identical semantic retries return the original immutable receipt, including after process recovery or terminal completion. JSON object order and decimal spelling do not affect identity. Success requires collecting_results or uploading_results and schema-valid outputs. Every declared file value requires a matching manifest entry naming a ready verified artifact produced by this assignment. Optional file failures are reported separately. Failure requires explicit termination confirmation and bounded failure details. Provider cleanup is acknowledged only after the result, artifact pins and terminal state commit; uncertain transfer remains outstanding without repeating computation.", "operationId": "put_result", "parameters": [ { "description": "Owned assignment; singleton operation identity.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Required active process session for the assignment's durable journal.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultRequest" } } }, "description": "Strict JSON object, at most 64 KiB or configured request limit, also bounded after decimal expansion. Duplicate fields at any depth and unknown fields are rejected. files maps declared names to canonical non-nil artifact_id references exactly matching outputs. execution_terminated must be true; absence of contact is insufficient. Outputs and explicit optional-output failures have distinct meanings.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultReceipt" } } }, "description": "Result, verified file pins and terminal state committed, or original immutable receipt replayed. provider_cleanup_acknowledged permits removal of provider work files only.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON, query parameters, or invalid_session_header.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active connector credential required and rechecked before persistence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Assignment invalid, absent or owned by another connector. Code not_found.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "result_conflict, attempt_conflict, invalid_transition, session_required or journal_conflict.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Body exceeds the 64 KiB or configured limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "JSON content type required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "invalid_request for unsupported structure or bounds; invalid_outputs for pinned output-schema or optional failure declaration mismatch.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "assignment_unavailable or assignment_uncertain. Retry the same assignment identity and saved body.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment_id}/uploads": { "post": { "description": "Reserve exact bytes with durable upload and artifact identities.\n\n**Credential scopes:** Separate connector bearer credential and assignment/session authority.\n\n**Resource authority:** Authenticated connector owns the exact assignment and holds its active X-Connector-Session.\n\n**Retry:** Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.\n\n**Guards:** New reservations select multipart strictly above 64 MiB. Single-PUT ceiling, per-file policy, declaration and aggregate quotas are independent. Existing reservations retain transport and expiry.\n\n**Retain:** Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.\n\n**Specific failures:** 400 invalid_idempotency_key; 409 idempotency_conflict; 413 metadata/body or general structural byte bound; 422 invalid_upload; 429 upload_quota_exceeded; 503 upload_uncertain; 404 not_found: unrelated assignment; 409 session_required, journal_conflict or invalid_transition\n\n**Next action:** Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification. [Worked workflow](/users/files/)", "operationId": "connector_create_upload", "parameters": [ { "description": "Owned assignment.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Active process session for this assignment journal.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Required once; 1–128 ASCII letters, digits, underscores or hyphens. Keep the same key/request after a lost response. Successful keys never expire.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadRequest" } } }, "description": "A bounded description, expected byte length and canonical full-object SHA-256. logical_name must name a declared file output; media type and size must satisfy its pinned declaration. Ownership and storage destination are inherited from the run. Publication does not finalize the run. No query parameters.", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadView" } } }, "description": "Durable reservation. Equivalent retries keep the original reservation receipt; current state and temporary transfer instructions are fresh. A storage outage returns transfer.status=unavailable without losing the reservation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "Location": { "description": "/connector/v1/assignments/{assignment_id}/uploads/{upload_id}", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON, query parameters, or invalid/repeated/missing idempotency key.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active connector credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unknown or unrelated assignment/upload.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "idempotency_conflict, output_upload_conflict, session_required, journal_conflict or invalid_transition. New uploads require collecting_results or uploading_results.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request exceeds 64 KiB or the file exceeds the structural transport limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "JSON content type required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "invalid_upload or invalid_outputs: invalid description, undeclared file output, unsupported media type or declaration byte limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "File admission or active transfer quota exhausted; keep the original operation and retry after capacity is reclaimed.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upload operation unavailable, storage not configured, or upload_uncertain: retry the same key and request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ], "x-enumeray-contract": { "errors": [ "400 invalid_idempotency_key", "409 idempotency_conflict", "413 metadata/body or general structural byte bound", "422 invalid_upload", "429 upload_quota_exceeded", "503 upload_uncertain", "404 not_found: unrelated assignment", "409 session_required, journal_conflict or invalid_transition" ], "guards": "New reservations select multipart strictly above 64 MiB. Single-PUT ceiling, per-file policy, declaration and aggregate quotas are independent. Existing reservations retain transport and expiry.", "method": "post", "next_action": "Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification.", "path": "/connector/v1/assignments/{assignment_id}/uploads", "purpose": "Reserve exact bytes with durable upload and artifact identities.", "retained": "Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.", "retry": "Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.", "roles": "Authenticated connector owns the exact assignment and holds its active X-Connector-Session.", "scopes": [], "workflow": "/users/files/" } } }, "/connector/v1/assignments/{assignment_id}/uploads/{upload_id}": { "get": { "description": "Inspect the original reservation and refresh temporary transfer instructions.\n\n**Credential scopes:** Separate connector bearer credential and assignment/session authority.\n\n**Resource authority:** Authenticated connector owns the exact assignment and holds its active X-Connector-Session.\n\n**Retry:** Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.\n\n**Guards:** New reservations select multipart strictly above 64 MiB. Single-PUT ceiling, per-file policy, declaration and aggregate quotas are independent. Existing reservations retain transport and expiry.\n\n**Retain:** Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.\n\n**Specific failures:** 400 bad_request; 404 not_found: missing or unauthorized upload; 503 upload_unavailable; 409 session_required or journal_conflict\n\n**Next action:** Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification. [Worked workflow](/users/files/)", "operationId": "connector_read_upload", "parameters": [ { "description": "Owned assignment.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Active process session for this assignment journal.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Upload reserved for this assignment.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadView" } } }, "description": "Current pending/expired/completed state. Pending uploads receive renewed PUT instructions only while the run is collecting_results or uploading_results. Completed uploads include their immutable completion receipt and issue no further transfer authority; expired uploads remain inspectable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid path or query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active connector credential and process session required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unknown and other-assignment upload IDs are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "session_required or journal_conflict.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upload status could not be read before its deadline.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ], "x-enumeray-contract": { "errors": [ "400 bad_request", "404 not_found: missing or unauthorized upload", "503 upload_unavailable", "409 session_required or journal_conflict" ], "guards": "New reservations select multipart strictly above 64 MiB. Single-PUT ceiling, per-file policy, declaration and aggregate quotas are independent. Existing reservations retain transport and expiry.", "method": "get", "next_action": "Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification.", "path": "/connector/v1/assignments/{assignment_id}/uploads/{upload_id}", "purpose": "Inspect the original reservation and refresh temporary transfer instructions.", "retained": "Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.", "retry": "Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.", "roles": "Authenticated connector owns the exact assignment and holds its active X-Connector-Session.", "scopes": [], "workflow": "/users/files/" } } }, "/connector/v1/assignments/{assignment_id}/uploads/{upload_id}/completion": { "put": { "description": "Verify and publish the exact stored version; multipart may return 202 while the worker verifies.\n\n**Credential scopes:** Separate connector bearer credential and assignment/session authority.\n\n**Resource authority:** Authenticated connector owns the exact assignment and holds its active X-Connector-Session.\n\n**Retry:** Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.\n\n**Guards:** New reservations select multipart strictly above 64 MiB. Single-PUT ceiling, per-file policy, declaration and aggregate quotas are independent. Existing reservations retain transport and expiry.\n\n**Retain:** Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.\n\n**Specific failures:** 400 bad_request; 404 not_found: missing or unauthorized upload; 409 upload_bytes_missing or upload_completion_conflict; 410 upload_expired; 413 completion JSON/body bound; 422 invalid_upload_completion or upload_verification_failed; 503 upload_uncertain; 409 session_required, journal_conflict or invalid_transition\n\n**Next action:** Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification. [Worked workflow](/users/files/)", "operationId": "connector_complete_upload", "parameters": [ { "description": "Owned assignment.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Active process session for this assignment journal.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Upload reserved for this assignment.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionBody" } } }, "description": "For single PUT use the non-null version_id returned by storage. For multipart use {multipart:true}; retry unchanged while HTTP 202 is returned. At most 8 KiB; no unknown/duplicate fields or query parameters. Save this request and retry it unchanged after a lost response. No additional idempotency key is needed.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadCompletionReceipt" } } }, "description": "Verified exact version published atomically. Identical retries return the original receipt, including after expiry or later storage unavailability, without republishing bytes. Downloads and file-input authorization are separate features.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Progress" } } }, "description": "Multipart assembly or exact-version verification is pending; retry the same multipart completion intent.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON, path or query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Active connector credential and process session required, rechecked before publication.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unknown and other-assignment uploads are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "upload_bytes_missing: storage reported no such version; upload_completion_conflict: a different version was already published; session_required, journal_conflict or invalid_transition before publication.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "upload_expired: unpublished reservation expired before publication.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Completion JSON exceeds 8 KiB or the deployment limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "JSON content type required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid completion request, or upload_verification_failed: exact-version metadata, byte size or native full-object SHA-256 differs or is absent.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Storage/database unavailable or upload_uncertain. Preserve and retry the same version request; inspect status to reconcile publication.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ], "x-enumeray-contract": { "errors": [ "400 bad_request", "404 not_found: missing or unauthorized upload", "409 upload_bytes_missing or upload_completion_conflict", "410 upload_expired", "413 completion JSON/body bound", "422 invalid_upload_completion or upload_verification_failed", "503 upload_uncertain", "409 session_required, journal_conflict or invalid_transition" ], "guards": "New reservations select multipart strictly above 64 MiB. Single-PUT ceiling, per-file policy, declaration and aggregate quotas are independent. Existing reservations retain transport and expiry.", "method": "put", "next_action": "Preserve the original operation; inspect to reconcile uncertainty; use completed artifact identity after verification.", "path": "/connector/v1/assignments/{assignment_id}/uploads/{upload_id}/completion", "purpose": "Verify and publish the exact stored version; multipart may return 202 while the worker verifies.", "retained": "Same account/assignment, source checksum and unchanged source bytes, original request/key, upload/artifact UUIDs, completion intent and confirmed parts.", "retry": "Reservation: retry original Idempotency-Key and body. Completion: retry original version_id or multipart:true intent. Current views may refresh temporary instructions; committed receipts retain their identities.", "roles": "Authenticated connector owns the exact assignment and holds its active X-Connector-Session.", "scopes": [], "workflow": "/users/files/" } } }, "/connector/v1/assignments/{assignment_id}/uploads/{upload_id}/multipart": { "delete": { "operationId": "connector_abort", "parameters": [ { "description": "Private upload reservation.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Owned assignment.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Current process session.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "202": { "description": "Transport initialization or verification is pending.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "204": { "description": "Checked multipart operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Part or lifecycle conflicts.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "description": "Reservation expired.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid part or integrity mismatch.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Retry the same operation after storage recovery.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment_id}/uploads/{upload_id}/parts": { "get": { "operationId": "connector_parts", "parameters": [ { "description": "Private upload reservation.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Owned assignment.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Current process session.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Exclusive part cursor; at most 100 descriptions per page.", "in": "query", "name": "after", "required": false, "schema": { "format": "int32", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartPage" } } }, "description": "Checked multipart operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "202": { "description": "Transport initialization or verification is pending.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Part or lifecycle conflicts.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "description": "Reservation expired.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid part or integrity mismatch.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Retry the same operation after storage recovery.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment_id}/uploads/{upload_id}/parts/{part_number}": { "put": { "operationId": "connector_authorize", "parameters": [ { "description": "Private upload reservation.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Owned assignment.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Current process session.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "One-based immutable part number.", "in": "path", "name": "part_number", "required": true, "schema": { "format": "int32", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartRequest" } } }, "description": "Immutable full-part SHA-256. Service derives exact size and offset; repeated identical requests refresh authorization.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartAuthorization" } } }, "description": "Checked multipart operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "202": { "description": "Transport initialization or verification is pending.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Part or lifecycle conflicts.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "description": "Reservation expired.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid part or integrity mismatch.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Retry the same operation after storage recovery.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment_id}/uploads/{upload_id}/parts/{part_number}/receipt": { "put": { "operationId": "connector_ack", "parameters": [ { "description": "Private upload reservation.", "in": "path", "name": "upload_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Owned assignment.", "in": "path", "name": "assignment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Current process session.", "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "One-based immutable part number.", "in": "path", "name": "part_number", "required": true, "schema": { "format": "int32", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartView" } } }, "description": "Checked multipart operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "202": { "description": "Transport initialization or verification is pending.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Part or lifecycle conflicts.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "410": { "description": "Reservation expired.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid part or integrity mismatch.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Retry the same operation after storage recovery.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/assignments/{assignment}/collections": { "post": { "description": "At most 64 KiB per request/page and 16 MiB per manifest. Freeze membership before binding members. Completion seals exact verified versions atomically. Replay original identities after uncertainty. Unknown/duplicate fields and query parameters are rejected, except the member cursor. Member pages contain at most 100 entries and 64 KiB; next_cursor is an immutable index, bound by the collection UUID. Every listed member is required. A sealed manifest remains historical evidence when bytes become unavailable.", "operationId": "connectorCollectionpost", "parameters": [ { "in": "path", "name": "assignment", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+$", "type": "string" } }, { "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionReceipt" } } }, "description": "Original receipt or bounded current view.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown and unauthorized collections are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Frozen evidence conflict or members not verified.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds its bound.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "description": "Collection writes require application/json.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid manifest, paths, metadata or member evidence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "Collection admission limit exceeded.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Unavailable or uncertain acknowledgement; repeat original operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "summary": "Immutable bounded collection metadata; member bytes use verified artifact uploads and downloads.", "tags": [ "Collections" ] } }, "/connector/v1/assignments/{assignment}/collections/{id}": { "get": { "description": "At most 64 KiB per request/page and 16 MiB per manifest. Freeze membership before binding members. Completion seals exact verified versions atomically. Replay original identities after uncertainty. Unknown/duplicate fields and query parameters are rejected, except the member cursor. Member pages contain at most 100 entries and 64 KiB; next_cursor is an immutable index, bound by the collection UUID. Every listed member is required. A sealed manifest remains historical evidence when bytes become unavailable.", "operationId": "connectorCollectionget_id", "parameters": [ { "in": "path", "name": "assignment", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionView" } } }, "description": "Original receipt or bounded current view.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown and unauthorized collections are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Frozen evidence conflict or members not verified.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds its bound.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "description": "Collection writes require application/json.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid manifest, paths, metadata or member evidence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "Collection admission limit exceeded.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Unavailable or uncertain acknowledgement; repeat original operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "summary": "Immutable bounded collection metadata; member bytes use verified artifact uploads and downloads.", "tags": [ "Collections" ] } }, "/connector/v1/assignments/{assignment}/collections/{id}/completion": { "put": { "description": "At most 64 KiB per request/page and 16 MiB per manifest. Freeze membership before binding members. Completion seals exact verified versions atomically. Replay original identities after uncertainty. Unknown/duplicate fields and query parameters are rejected, except the member cursor. Member pages contain at most 100 entries and 64 KiB; next_cursor is an immutable index, bound by the collection UUID. Every listed member is required. A sealed manifest remains historical evidence when bytes become unavailable.", "operationId": "connectorCollectionput_id_completion", "parameters": [ { "in": "path", "name": "assignment", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionView" } } }, "description": "Original receipt or bounded current view.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown and unauthorized collections are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Frozen evidence conflict or members not verified.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds its bound.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "description": "Collection writes require application/json.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid manifest, paths, metadata or member evidence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "Collection admission limit exceeded.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Unavailable or uncertain acknowledgement; repeat original operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "summary": "Immutable bounded collection metadata; member bytes use verified artifact uploads and downloads.", "tags": [ "Collections" ] } }, "/connector/v1/assignments/{assignment}/collections/{id}/freeze": { "put": { "description": "At most 64 KiB per request/page and 16 MiB per manifest. Freeze membership before binding members. Completion seals exact verified versions atomically. Replay original identities after uncertainty. Unknown/duplicate fields and query parameters are rejected, except the member cursor. Member pages contain at most 100 entries and 64 KiB; next_cursor is an immutable index, bound by the collection UUID. Every listed member is required. A sealed manifest remains historical evidence when bytes become unavailable.", "operationId": "connectorCollectionput_id_freeze", "parameters": [ { "in": "path", "name": "assignment", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionFreezeReceipt" } } }, "description": "Original receipt or bounded current view.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown and unauthorized collections are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Frozen evidence conflict or members not verified.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds its bound.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "description": "Collection writes require application/json.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid manifest, paths, metadata or member evidence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "Collection admission limit exceeded.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Unavailable or uncertain acknowledgement; repeat original operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "summary": "Immutable bounded collection metadata; member bytes use verified artifact uploads and downloads.", "tags": [ "Collections" ] } }, "/connector/v1/assignments/{assignment}/collections/{id}/members": { "get": { "description": "At most 64 KiB per request/page and 16 MiB per manifest. Freeze membership before binding members. Completion seals exact verified versions atomically. Replay original identities after uncertainty. Unknown/duplicate fields and query parameters are rejected, except the member cursor. Member pages contain at most 100 entries and 64 KiB; next_cursor is an immutable index, bound by the collection UUID. Every listed member is required. A sealed manifest remains historical evidence when bytes become unavailable.", "operationId": "connectorCollectionget_id_members", "parameters": [ { "in": "path", "name": "assignment", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "default": 0, "maximum": 10000, "minimum": 0, "type": "integer" } }, { "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberPage" } } }, "description": "Original receipt or bounded current view.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown and unauthorized collections are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Frozen evidence conflict or members not verified.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds its bound.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "description": "Collection writes require application/json.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid manifest, paths, metadata or member evidence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "Collection admission limit exceeded.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Unavailable or uncertain acknowledgement; repeat original operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "summary": "Immutable bounded collection metadata; member bytes use verified artifact uploads and downloads.", "tags": [ "Collections" ] } }, "/connector/v1/assignments/{assignment}/collections/{id}/members/{index}": { "put": { "description": "At most 64 KiB per request/page and 16 MiB per manifest. Freeze membership before binding members. Completion seals exact verified versions atomically. Replay original identities after uncertainty. Unknown/duplicate fields and query parameters are rejected, except the member cursor. Member pages contain at most 100 entries and 64 KiB; next_cursor is an immutable index, bound by the collection UUID. Every listed member is required. A sealed manifest remains historical evidence when bytes become unavailable.", "operationId": "connectorCollectionput_id_members_index", "parameters": [ { "in": "path", "name": "assignment", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "maximum": 9999, "minimum": 0, "type": "integer" } }, { "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/MemberSpec" }, "maxItems": 10000, "type": "array" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionPageReceipt" } } }, "description": "Original receipt or bounded current view.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown and unauthorized collections are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Frozen evidence conflict or members not verified.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds its bound.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "description": "Collection writes require application/json.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid manifest, paths, metadata or member evidence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "Collection admission limit exceeded.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Unavailable or uncertain acknowledgement; repeat original operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "summary": "Immutable bounded collection metadata; member bytes use verified artifact uploads and downloads.", "tags": [ "Collections" ] } }, "/connector/v1/assignments/{assignment}/collections/{id}/members/{index}/artifact": { "put": { "description": "At most 64 KiB per request/page and 16 MiB per manifest. Freeze membership before binding members. Completion seals exact verified versions atomically. Replay original identities after uncertainty. Unknown/duplicate fields and query parameters are rejected, except the member cursor. Member pages contain at most 100 entries and 64 KiB; next_cursor is an immutable index, bound by the collection UUID. Every listed member is required. A sealed manifest remains historical evidence when bytes become unavailable.", "operationId": "connectorCollectionput_id_members_index_artifact", "parameters": [ { "in": "path", "name": "assignment", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "maximum": 9999, "minimum": 0, "type": "integer" } }, { "in": "header", "name": "X-Connector-Session", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "artifact_id": { "format": "uuid", "type": "string" } }, "required": [ "artifact_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionBindingReceipt" } } }, "description": "Original receipt or bounded current view.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "description": "Active credential required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "description": "Unknown and unauthorized collections are indistinguishable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "description": "Frozen evidence conflict or members not verified.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds its bound.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "description": "Collection writes require application/json.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "description": "Invalid manifest, paths, metadata or member evidence.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "429": { "description": "Collection admission limit exceeded.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "description": "Unavailable or uncertain acknowledgement; repeat original operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "summary": "Immutable bounded collection metadata; member bytes use verified artifact uploads and downloads.", "tags": [ "Collections" ] } }, "/connector/v1/configuration": { "get": { "operationId": "selfservice_get_connector_v1_configuration", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesiredConfiguration" } } }, "description": "Pull retained contexts and immutable publication snapshots, including exact configuration generations and the default-false reserved run payload namespace capability.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "summary": "Pull retained contexts and immutable publication snapshots, including exact configuration generations and the default-false reserved run payload namespace capability.", "tags": [ "Connectors" ] } }, "/connector/v1/configuration/{generation}/ack": { "put": { "operationId": "selfservice_put_connector_v1_configuration__generation__ack", "parameters": [ { "in": "path", "name": "generation", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationAcknowledgment" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Report a bounded subset of installation validations for the exact desired configuration generation, including observed digests. Stale generations are rejected; observed_generation advances only after every publication has reported for that generation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "summary": "Report a bounded subset of installation validations for the exact desired configuration generation, including observed digests. Stale generations are rejected; observed_generation advances only after every publication has reported for that generation.", "tags": [ "Connectors" ] } }, "/connector/v1/configuration/{generation}/retention-dispositions": { "post": { "operationId": "selfservice_post_connector_v1_configuration__generation__retention_dispositions", "parameters": [ { "in": "path", "name": "generation", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRetentionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRetentionReceipt" } } }, "description": "Finalize at most 128 eligible retirement requests at the exact connector generation and inspect at most 128 cache identities. A changed generation requires a fresh configuration snapshot. Only positive eligible dispositions permit pruning after local assignment and cleanup pins clear; unmanaged keys and mere snapshot absence never authorize deletion.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "summary": "Finalize at most 128 eligible retirement requests at the exact connector generation and inspect at most 128 cache identities. A changed generation requires a fresh configuration snapshot. Only positive eligible dispositions permit pruning after local assignment and cleanup pins clear; unmanaged keys and mere snapshot absence never authorize deletion.", "tags": [ "Connectors" ] } }, "/connector/v1/enroll": { "post": { "operationId": "selfservice_post_connector_v1_enroll", "requestBody": { "content": { "application/json": { "examples": { "enroll-connector": { "description": "Valid one-time enrollment shape and removal of an existing co-administrator. Fixture verifier is SHA-256 of a nonsecret fixture token.", "summary": "enroll-connector", "value": { "credential_id": "00000000-0000-4000-8000-000000000008", "enrollment_token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "machine_id": "00000000-0000-4000-8000-000000000009", "token_verifier": "b255d443632f58a48e6e071ed1a9243fb4de190c1245e8349979b96e3367d52d" } } }, "schema": { "$ref": "#/components/schemas/EnrollmentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "enroll-connector": { "description": "Valid one-time enrollment shape and removal of an existing co-administrator. Fixture verifier is SHA-256 of a nonsecret fixture token.", "summary": "enroll-connector", "value": { "connector_id": "lab-connector", "credential_id": "00000000-0000-4000-8000-000000000008" } } }, "schema": { "$ref": "#/components/schemas/EnrollmentReceipt" } } }, "description": "Redeem a one-time enrollment for a persisted machine and locally generated credential identity.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Valid active credential required; connector and user credentials are separate.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The token does not permit this operation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource absent or outside the caller's authority.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Concurrent generation/publication change, conflicting retry, or a publication awaiting connector validation.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request fields, manifest, installation policy, or limits are invalid.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication, identity provider, or management state is temporarily unavailable.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/HttpError" } }, "summary": "Redeem a one-time enrollment for a persisted machine and locally generated credential identity.", "tags": [ "Connectors" ] } }, "/connector/v1/heartbeat": { "put": { "operationId": "heartbeat", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatRequest" } } }, "description": "At most 8 KiB, also subject to the configured global limit. No query parameters or unknown fields. Capabilities are at most 32 unique lowercase identifiers (1–64 ASCII bytes); wrapper versions are at most 16 unique positive u32 values. Unknown capability names and wrapper versions are observations, not execution permission.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatReceipt" } } }, "description": "The authenticated connector's report was committed. Retries may advance receipt time without affecting runs.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON or query parameters. Code bad_request.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, invalid, wrong-kind, or revoked connector credential. Code unauthenticated.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Heartbeat body exceeds its route or configured request limit. Code payload_too_large.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A JSON content type is required. Code unsupported_media_type.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid JSON structure (invalid_request) or report values (invalid_heartbeat).", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication or heartbeat persistence unavailable. Codes authentication_unavailable and heartbeat_unavailable. Retry the current report; an uncertain acknowledgement may already have committed.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/preflights": { "get": { "operationId": "pending", "parameters": [ { "in": "query", "name": "session_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PendingPreflight" }, "type": "array" } } }, "description": "", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "crate::management::preflight" ] } }, "/connector/v1/preflights/{request_id}/report": { "put": { "operationId": "report", "parameters": [ { "in": "path", "name": "request_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightSubmission" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "crate::management::preflight" ] } }, "/connector/v1/sessions": { "post": { "operationId": "acquire_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionReceipt" } } }, "description": "The process owns this connector's durable journal. Identical acquisition retries return the same identity.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON or unexpected query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connector credential.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "journal_conflict, session_busy, or session_closed. No timed takeover is permitted.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Body exceeds the 8 KiB or configured limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "JSON content type required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid structure or ownership identifiers.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Coordination unavailable or commit uncertain. Retry identical session identity.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/sessions/recover": { "post": { "operationId": "recover_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionRecoveryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionReceipt" } } }, "description": "Explicit same-journal recovery committed, or exact retry of this active successor. Caller must have stopped the previous owning process. Assignment identities and execution outcomes are unchanged.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON or unexpected query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid or revoked connector credential.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Prior session absent or outside this connector and journal.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "journal_conflict, session_busy, or session_closed. Stale recovery cannot replace a successor or reopen a closed session.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Body exceeds the 8 KiB or configured limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "JSON content type required.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid structure or identities; prior_process_stopped must be true.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Coordination unavailable or commit uncertain. Persist and retry the identical recovery transition.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } }, "/connector/v1/sessions/{session_id}": { "delete": { "operationId": "release_session", "parameters": [ { "description": "Owned process session; keep the journal and unresolved assignments.", "in": "path", "name": "session_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Process ownership released, or this same session was already released. Journal and assignments remain.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid path, nonempty body, or unexpected query parameters.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connector credential.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "WWW-Authenticate": { "description": "Bearer", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Session absent or belongs to another connector.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "413: the request body exceeds the configured size limit.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Coordination unavailable or commit uncertain; retry the same release.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An HTTP request failed; inspect the stable error code and request ID.", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "x-request-id": { "description": "Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body's request_id.", "schema": { "type": "string" } } } } }, "security": [ { "connector_bearer": [] } ], "tags": [ "Connectors" ] } } }, "x-enumeray-limits": { "archive_compressed_default_bytes": 52428800, "archive_structural_maximum_bytes": 536870912, "artifact_structural_maximum_bytes": 53687091200000, "destination_outstanding_default_bytes": 10995116277760, "file_admission_default_bytes": 107374182400, "multipart_threshold_bytes": 67108864, "owner_outstanding_default_bytes": 1099511627776, "request_body_default_bytes": 1048576, "request_body_maximum_bytes": 16777216, "run_attachment_maximum_count": 8, "run_direction_default_bytes": 1099511627776, "run_input_json_maximum_bytes": 65536, "run_json_part_maximum_bytes": 1048576, "single_put_maximum_bytes": 5368709120, "token_page_default": 50, "token_page_maximum": 100 } }