{ "components": { "schemas": { "Admission": { "additionalProperties": false, "description": "a repository admission", "properties": { "merge_base": { "description": "the resolved merge base commit", "type": "string" } }, "required": [ "merge_base" ], "type": "object" }, "Advisory": { "additionalProperties": false, "description": "a live advisory", "properties": { "id": { "description": "the advisory id", "type": "string" }, "remediation_href": { "description": "where to act", "type": "string" }, "repository": { "description": "owner/name", "type": "string" }, "text": { "description": "the recommendation with its measured value", "type": "string" } }, "required": [ "id", "repository", "text", "remediation_href" ], "type": "object" }, "AdvisoryDetail": { "additionalProperties": false, "description": "an advisory with its basis", "properties": { "basis_signature": { "description": "the basis signature", "type": "string" }, "id": { "description": "the advisory id", "type": "string" }, "key": { "description": "the advisory key", "type": "string" }, "measured_value": { "description": "the measured value", "type": "string" }, "recommendation": { "description": "the recommendation", "type": "string" }, "remediation_href": { "description": "where to act", "type": "string" } }, "required": [ "id", "key", "measured_value", "basis_signature", "recommendation", "remediation_href" ], "type": "object" }, "AnyValue": { "description": "any JSON value" }, "ArtifactInventory": { "additionalProperties": true, "description": "the published artifact inventory: expiry and publications with their files", "type": "object" }, "AuditEntry": { "additionalProperties": false, "description": "an attributed mutation", "properties": { "actor": { "description": "the principal", "type": "string" }, "changed_at": { "description": "when, as RFC 3339", "type": "string" }, "effective": { "description": "from when it applies", "type": "string" }, "target": { "description": "what changed", "type": "string" }, "value": { "description": "the value recorded", "type": "string" } }, "required": [ "actor", "target", "value", "changed_at", "effective" ], "type": "object" }, "AuditPage": { "additionalProperties": false, "description": "a page of audit entries", "properties": { "entries": { "description": "newest first", "items": { "$ref": "#/components/schemas/AuditEntry" }, "type": "array" }, "next_cursor": { "oneOf": [ { "description": "the opaque cursor of the next page, absent when this page is the last", "type": "string" }, { "type": "null" } ] } }, "required": [ "entries", "next_cursor" ], "type": "object" }, "AuditRefusal": { "additionalProperties": true, "description": "the refused mutation, itself audited", "type": "object" }, "CanaryAttribution": { "additionalProperties": true, "description": "a canary job's attribution", "type": "object" }, "CancellationReceipt": { "additionalProperties": false, "description": "a requested cancellation", "properties": { "job": { "description": "the job", "type": "string" }, "requested_by": { "description": "the principal", "type": "string" }, "state": { "description": "cancellation_requested", "type": "string" } }, "required": [ "job", "state", "requested_by" ], "type": "object" }, "CargoSource": { "oneOf": [ { "additionalProperties": false, "description": "legacy inline snapshot", "properties": { "files": { "description": "complete sorted regular files", "items": { "additionalProperties": false, "description": "one regular source file", "properties": { "bytes": { "description": "original bytes", "items": { "maximum": 255, "minimum": 0, "type": "integer" }, "type": "array" }, "executable": { "description": "preserve the executable mode", "type": "boolean" }, "path": { "description": "canonical repository-relative path", "type": "string" } }, "required": [ "path", "bytes", "executable" ], "type": "object" }, "type": "array" } }, "required": [ "files" ], "type": "object" }, { "additionalProperties": false, "description": "streamed source; archive contents are outside the job document", "properties": { "archive": { "$ref": "#/components/schemas/SourceReference" } }, "required": [ "archive" ], "type": "object" } ] }, "CargoWorkspaceRequest": { "additionalProperties": false, "description": "a captured Cargo workspace submission", "properties": { "check": { "additionalProperties": false, "description": "optional: the commit a GitHub check run named lathe reports this job for, through the tenant's installation covering the repository", "properties": { "head_sha": { "description": "exact 40-character lowercase commit id", "type": "string" } }, "required": [ "head_sha" ], "type": "object" }, "repository": { "description": "owner/name", "type": "string" }, "schema_version": { "description": "1 for legacy inline source; 2 for a verified streamed archive reference", "enum": [ 1, 2 ], "type": "integer" }, "size": { "description": "the microVM shape on the wire: lathe2-cpu, lathe4-cpu, lathe8-cpu or lathe16-cpu", "enum": [ "lathe2-cpu", "lathe4-cpu", "lathe8-cpu", "lathe16-cpu" ], "type": "string" }, "workspace": { "additionalProperties": false, "description": "the original captured Cargo input", "properties": { "base_commit": { "description": "declared Git base revision; captured bytes remain authoritative", "type": "string" }, "branch": { "description": "declared Git branch", "type": "string" }, "invocation": { "additionalProperties": true, "description": "exact Cargo operation, pinned toolchain, arguments, working_directory, artifacts and explicit environment", "type": "object" }, "source": { "$ref": "#/components/schemas/CargoSource" } }, "required": [ "base_commit", "branch", "invocation", "source" ], "type": "object" } }, "required": [ "schema_version", "repository", "size", "workspace" ], "type": "object" }, "ClaimReceipt": { "additionalProperties": false, "description": "a claimed installation", "properties": { "claimed_by": { "description": "the principal that claimed it", "type": "string" }, "installation_id": { "description": "the installation id", "type": "integer" }, "tenant": { "description": "the tenant it is linked to", "type": "string" } }, "required": [ "installation_id", "tenant", "claimed_by" ], "type": "object" }, "ClaimRequest": { "additionalProperties": false, "description": "an installation claim", "properties": { "installation_id": { "description": "the GitHub App installation id", "type": "integer" } }, "required": [ "installation_id" ], "type": "object" }, "Credential": { "additionalProperties": false, "description": "an agent credential", "properties": { "created_at": { "description": "creation, as RFC 3339", "type": "string" }, "created_by": { "description": "the admin who minted it", "type": "string" }, "expires_at": { "description": "expiry, as RFC 3339", "type": "string" }, "last_used_at": { "oneOf": [ { "description": "last use, as RFC 3339", "type": "string" }, { "type": "null" } ] }, "name": { "description": "the name", "type": "string" }, "principal": { "description": "agent:", "type": "string" }, "requests_per_minute": { "description": "the credential's request limit", "type": "integer" }, "revoked_at": { "oneOf": [ { "description": "revocation, as RFC 3339", "type": "string" }, { "type": "null" } ] }, "revoked_by": { "oneOf": [ { "description": "who revoked it", "type": "string" }, { "type": "null" } ] }, "scopes": { "description": "the scopes", "items": { "description": "a credential scope", "enum": [ "read", "submit", "settings", "credentials", "admin" ], "type": "string" }, "type": "array" } }, "required": [ "name", "principal", "scopes", "created_by", "created_at", "expires_at", "last_used_at", "revoked_at", "revoked_by", "requests_per_minute" ], "type": "object" }, "CredentialIssued": { "additionalProperties": false, "description": "a minted credential, shown once", "properties": { "credential": { "description": "the credential value; never shown again", "type": "string" }, "view": { "$ref": "#/components/schemas/Credential" } }, "required": [ "credential", "view" ], "type": "object" }, "CredentialRequest": { "additionalProperties": false, "description": "an agent credential to mint", "properties": { "expires_in_seconds": { "description": "seconds until expiry, 60 to 31536000", "type": "integer" }, "name": { "description": "[a-z0-9][a-z0-9-]{0,62}, unique among the tenant's live credentials", "type": "string" }, "requests_per_minute": { "oneOf": [ { "description": "requests per minute; 600 by default", "type": "integer" }, { "type": "null" } ] }, "scopes": { "description": "the scopes", "items": { "description": "a credential scope", "enum": [ "read", "submit", "settings", "credentials", "admin" ], "type": "string" }, "type": "array" } }, "required": [ "name", "scopes", "expires_in_seconds" ], "type": "object" }, "CredentialRevocationReceipt": { "additionalProperties": false, "description": "a revoked credential", "properties": { "name": { "description": "the name", "type": "string" }, "revoked_at": { "description": "when, as RFC 3339", "type": "string" }, "revoked_by": { "description": "the principal", "type": "string" } }, "required": [ "name", "revoked_at", "revoked_by" ], "type": "object" }, "CredentialsPage": { "additionalProperties": false, "description": "a page of credentials", "properties": { "credentials": { "description": "the page", "items": { "$ref": "#/components/schemas/Credential" }, "type": "array" }, "next_cursor": { "oneOf": [ { "description": "the opaque cursor of the next page, absent when this page is the last", "type": "string" }, { "type": "null" } ] } }, "required": [ "credentials", "next_cursor" ], "type": "object" }, "DestructiveApproval": { "additionalProperties": true, "description": "an approval naming the host, the incident and the step it admits", "type": "object" }, "DestructiveStepApproval": { "additionalProperties": false, "description": "the destructive step an approval admits", "properties": { "step": { "description": "reinstallation, partitioning or filesystem_operation", "type": "string" } }, "required": [ "step" ], "type": "object" }, "DeviceApprovalReceipt": { "additionalProperties": false, "description": "an approved device code", "properties": { "approved_by": { "description": "the person who approved it", "type": "string" }, "user_code": { "description": "the approved user code", "type": "string" } }, "required": [ "user_code", "approved_by" ], "type": "object" }, "DeviceAuthorization": { "additionalProperties": false, "description": "a started device authorization", "properties": { "device_code": { "description": "the code the CLI polls with", "type": "string" }, "expires_at": { "description": "when the authorization expires, as RFC 3339", "type": "string" }, "interval_seconds": { "description": "the polling interval", "type": "integer" }, "requesting_host": { "description": "the host that started the flow", "type": "string" }, "user_code": { "description": "the code a person confirms", "type": "string" }, "verification_uri": { "description": "the approval page naming the user code", "type": "string" } }, "required": [ "device_code", "user_code", "verification_uri", "expires_at", "interval_seconds", "requesting_host" ], "type": "object" }, "DevicePoll": { "additionalProperties": true, "description": "the poll state: pending, approved with the token once, expired or limited; the `state` member names which", "type": "object" }, "DismissalReceipt": { "additionalProperties": false, "description": "a dismissed advisory", "properties": { "advisory": { "description": "the advisory id", "type": "string" }, "dismissed_by": { "description": "the principal", "type": "string" } }, "required": [ "advisory", "dismissed_by" ], "type": "object" }, "DogfoodGateEvidenceRecorded": { "additionalProperties": true, "description": "the evidence as recorded with its source, whether it was newly recorded, the gate after the recording and the clock the recording started", "type": "object" }, "DogfoodGateEvidenceRequest": { "additionalProperties": false, "description": "gate evidence to verify against the platform's own records and record", "properties": { "detail": { "description": "for an attested reference only: what the operator attests it shows", "type": "string" }, "expires_at": { "description": "when the evidence stops meeting the part, as RFC 3339", "type": "string" }, "part": { "description": "the gate part the evidence meets", "enum": [ "a0_verdict", "a1_outcomes", "no_duplicate_settlement", "continuous_observation", "certificate_renewal", "expired_identity_recovery", "reboot_recovery", "staged_release_reverted", "alerts_observed", "off_host_evidence_observed", "provider_unavailable_recovery", "cold_darm_run", "transport_qualified_production", "transport_qualified_staging", "submitter_credential" ], "type": "string" }, "produced_at": { "description": "for an attested reference only: when the evidence was produced, as RFC 3339", "type": "string" }, "reference": { "description": "a run record identity, credential: or one issuance credential::, a GitHub Actions run of the dogfood repository, or an https reference an operator attests", "type": "string" } }, "required": [ "part", "reference" ], "type": "object" }, "DogfoodIncident": { "additionalProperties": true, "description": "an incident with its class, when it occurred, its issue and its resolution", "type": "object" }, "DogfoodIncidentIssueRequest": { "additionalProperties": false, "description": "the issue an operator filed for an incident", "properties": { "filed_at": { "description": "when the issue was filed, as GitHub shows it, as RFC 3339", "type": "string" }, "incident": { "description": "the incident identifier", "type": "string" }, "number": { "description": "the issue number in the dogfood repository", "type": "integer" } }, "required": [ "incident", "number", "filed_at" ], "type": "object" }, "DogfoodIncidentRequest": { "additionalProperties": false, "description": "an incident an operator found", "properties": { "class": { "description": "the incident class; the platform records unexpected outages and bounded recoveries itself", "enum": [ "wrong_green", "cross_tenant_disclosure", "duplicate_execution", "duplicate_charge", "declared" ], "type": "string" }, "detail": { "description": "what happened", "type": "string" }, "id": { "description": "the incident identifier", "type": "string" }, "occurred_at": { "description": "when the incident occurred, as RFC 3339", "type": "string" }, "records": { "description": "the run records that exposed it; a zero-tolerance class names at least one", "items": { "description": "a run record identity", "type": "string" }, "type": "array" }, "service_blocking": { "description": "whether the incident blocks service", "type": "boolean" } }, "required": [ "id", "class", "occurred_at", "service_blocking", "detail" ], "type": "object" }, "DogfoodIncidentResolutionRequest": { "additionalProperties": false, "description": "an operator's resolution of an incident", "properties": { "detail": { "description": "what resolved it: the fix, its pull request or the finding", "type": "string" }, "incident": { "description": "the incident identifier", "type": "string" } }, "required": [ "incident", "detail" ], "type": "object" }, "DogfoodIntervention": { "additionalProperties": true, "description": "the owner intervention as recorded, with who recorded it", "type": "object" }, "DogfoodInterventionRequest": { "additionalProperties": false, "description": "an owner action taken during the period", "properties": { "action": { "description": "what the owner did", "type": "string" }, "at": { "description": "when the owner acted, as RFC 3339", "type": "string" }, "id": { "description": "the intervention identifier", "type": "string" }, "records": { "description": "the run records the action touched", "items": { "description": "a run record identity", "type": "string" }, "type": "array" }, "routine": { "description": "whether the platform was specified to take the action itself", "type": "boolean" } }, "required": [ "id", "action", "routine", "at" ], "type": "object" }, "DogfoodLifecycleChange": { "additionalProperties": true, "description": "the lifecycle change as recorded, with who recorded it", "type": "object" }, "DogfoodLifecycleChangeRequest": { "additionalProperties": false, "description": "a material lifecycle change the probes cannot show", "properties": { "at": { "description": "when the change took effect, as RFC 3339", "type": "string" }, "detail": { "description": "what changed", "type": "string" }, "host": { "description": "the host the change touched", "type": "string" }, "identity": { "description": "the generation, the release digest or the new identity", "type": "string" }, "kind": { "description": "the kind of change", "enum": [ "host_generation", "host_reinstall", "guest_image_release", "host_identity" ], "type": "string" } }, "required": [ "kind", "identity", "at", "detail" ], "type": "object" }, "DogfoodMaintenance": { "additionalProperties": true, "description": "the maintenance declaration as recorded, with who declared it and when", "type": "object" }, "DogfoodMaintenanceRequest": { "additionalProperties": false, "description": "an interval of at most 24 hours declared as maintenance before it begins", "properties": { "ends_at": { "description": "when the maintenance ends, as RFC 3339", "type": "string" }, "id": { "description": "the declaration identifier", "type": "string" }, "reason": { "description": "why the platform is maintained", "type": "string" }, "starts_at": { "description": "when the maintenance starts, as RFC 3339", "type": "string" } }, "required": [ "id", "starts_at", "ends_at", "reason" ], "type": "object" }, "DogfoodPeriod": { "additionalProperties": true, "description": "the entry gate with each condition's parts and, for each, the evidence that meets it or what it lacks; the period's state, its clock and closed windows; every incident with its issue and resolution; the scorecard; and, once the period has ended, the beta decision record", "type": "object" }, "DogfoodRunRecord": { "additionalProperties": true, "description": "a dogfood run record: every field, each absent one with its reason; its threshold labels; and every incident that names it, with its issue and resolution", "type": "object" }, "DogfoodSpend": { "additionalProperties": true, "description": "the spend as recorded, with who recorded it and when", "type": "object" }, "DogfoodSpendRequest": { "additionalProperties": false, "description": "spend for one month from one provider or invoice", "properties": { "amount_cents": { "description": "the amount, in cents", "type": "integer" }, "month": { "description": "the month, as YYYY-MM", "type": "string" }, "source": { "description": "the provider or invoice the amount comes from", "type": "string" } }, "required": [ "month", "source", "amount_cents" ], "type": "object" }, "FirstJob": { "additionalProperties": false, "description": "the newest job", "properties": { "id": { "description": "the job id", "type": "string" }, "repository": { "description": "its repository", "type": "string" } }, "required": [ "id", "repository" ], "type": "object" }, "FlagDispositionRequest": { "additionalProperties": true, "description": "the disposition and its note", "type": "object" }, "HostActivations": { "additionalProperties": true, "description": "a host's in-place activations: admission and the host operator's closure, the host operation, the host operator's readiness, the current boot, and each activation's plan and ledger with its receipt once it finished", "type": "object" }, "HostDeploymentRequest": { "additionalProperties": true, "description": "the deployed release", "type": "object" }, "HostDetail": { "additionalProperties": true, "description": "a host's serving state, drain attribution, blockers and receipts", "type": "object" }, "HostIncident": { "additionalProperties": true, "description": "an incident with the automatic recoveries it has spent, whether it awaits an operator and why, and its approvals", "type": "object" }, "HostIncidentClose": { "additionalProperties": false, "description": "an operator's close of an incident", "properties": { "expected_revision": { "description": "the incident revision the operator read", "type": "integer" } }, "required": [ "expected_revision" ], "type": "object" }, "HostInitialization": { "additionalProperties": true, "description": "the recorded initialization state", "type": "object" }, "HostInitializationRequest": { "additionalProperties": true, "description": "the initialization inputs", "type": "object" }, "HostInventory": { "description": "hosts", "items": { "$ref": "#/components/schemas/HostInventoryView" }, "type": "array" }, "HostInventoryView": { "additionalProperties": true, "description": "a host row: host, state, revision, deployed release and last attribution", "type": "object" }, "HostRecovery": { "additionalProperties": true, "description": "a host's recovery: admission and the host operator's closure, the host operation, the policy, the incident with what it has spent and whether it awaits an operator, the newest recovery with its step ledger and who began it, and the recorded invocations", "type": "object" }, "HostRecoveryInvocation": { "additionalProperties": false, "description": "an invocation of a host recovery", "properties": { "confirmation": { "description": "recover-boot::preserve-root-and-srv", "type": "string" }, "expected_revision": { "description": "the host operation revision the operator read", "type": "integer" }, "incident": { "description": "the incident the invocation answers", "type": "string" }, "request": { "description": "a request identifier, so a retry replays the recorded invocation", "type": "string" }, "rescue_read": { "description": "read the wedged boot's journal from the rescue system first", "type": "boolean" }, "rescue_ssh_public_key": { "description": "the one-run rescue public key, only with rescue_read", "type": "string" }, "surface": { "description": "operator_api (the default) or command_line", "type": "string" } }, "required": [ "confirmation" ], "type": "object" }, "HostRecoveryInvocationOutcome": { "additionalProperties": true, "description": "recorded, with the operation and request; or in_progress, with the operation already open or running", "type": "object" }, "HostRecoveryPolicy": { "additionalProperties": true, "description": "the host's recovery policy and its revision", "type": "object" }, "HostRecoveryPolicyUpdate": { "additionalProperties": false, "description": "whether the host operator takes automatic recovery for the host", "properties": { "automatic": { "description": "automatic recovery enabled", "type": "boolean" }, "expected_revision": { "description": "the policy revision read; absent only while none is set", "type": "integer" } }, "required": [ "automatic" ], "type": "object" }, "HostTransitions": { "description": "host lifecycle transitions", "items": { "additionalProperties": true, "description": "a transition", "type": "object" }, "type": "array" }, "Identity": { "additionalProperties": false, "description": "the calling principal", "properties": { "display_name": { "description": "the display name", "type": "string" }, "installation_active": { "oneOf": [ { "description": "whether the GitHub App installation is claimed, when the runtime can claim", "type": "boolean" }, { "type": "null" } ] }, "kind": { "description": "person or agent", "enum": [ "person", "agent" ], "type": "string" }, "memberships": { "description": "the person's memberships", "items": { "$ref": "#/components/schemas/Membership" }, "type": "array" }, "principal": { "description": "the principal id attributed on jobs, settings and audit entries", "type": "string" }, "role": { "oneOf": [ { "description": "the person's role, absent for an agent", "type": "string" }, { "type": "null" } ] }, "scopes": { "description": "the scopes the principal holds", "items": { "description": "a credential scope", "enum": [ "read", "submit", "settings", "credentials", "admin" ], "type": "string" }, "type": "array" }, "sign_out_available": { "description": "hosted sign-in is active", "type": "boolean" }, "tenant": { "description": "the active tenant", "type": "string" }, "user_id": { "oneOf": [ { "description": "the person's user id", "type": "string" }, { "type": "null" } ] } }, "required": [ "principal", "kind", "user_id", "display_name", "tenant", "role", "scopes", "memberships", "installation_active", "sign_out_available" ], "type": "object" }, "IdentityInventory": { "additionalProperties": true, "description": "every host certificate, outstanding bootstrap credential, controller and provisioner identity: its role, subject, certificate digest, issuer, not-before and not-after instants, remaining seconds and fraction, or the named reason it has no window; for a host, the recovery key its enrollment records, by digest, or why there is none", "type": "object" }, "Job": { "additionalProperties": true, "description": "the authoritative job record: id, tenant, submitted_by, description, repo, branch, sha_short, class, status, accepted_at, queued_at, started_at, finished_at, units, transitions, failure and queue_annotation; a dependency-gateway workspace carries its generated dependency configuration as configuration_sha256 with the locked crates and git sources it was generated from, never as text", "type": "object" }, "JobEvidence": { "additionalProperties": false, "description": "a job with its evidence", "properties": { "attempts": { "oneOf": [ { "additionalProperties": true, "description": "the attempt evidence page with its cursor", "type": "object" }, { "type": "null" } ] }, "job": { "$ref": "#/components/schemas/Job" }, "report": { "additionalProperties": true, "description": "the evidence report: phases, crates, caches, injections (each build setting with its value, origin, `applied` or `not applied` status and the detail of what it set or why not), tests and units; for a captured Cargo workspace job, `admitted` carries the admitted toolchain, its origin, the network policy (offline or dependency-gateway) and, for a dependency-gateway job, the SHA-256 of the generated dependency configuration", "type": "object" }, "settlement": { "oneOf": [ { "additionalProperties": true, "description": "the retained usage settlement once the terminal job settled; a job cancelled before placement settles explicitly with no attempt and no usage record", "type": "object" }, { "type": "null" } ] }, "usage": { "oneOf": [ { "additionalProperties": true, "description": "the usage record when metering has closed", "type": "object" }, { "type": "null" } ] } }, "required": [ "job", "report", "usage" ], "type": "object" }, "JobId": { "description": "the job identifier", "type": "string" }, "JobLogPage": { "additionalProperties": true, "description": "a page of job log records with next_cursor, gaps, pending ranges, watermarks and whether the log settled", "type": "object" }, "JobsPage": { "additionalProperties": false, "description": "a page of jobs", "properties": { "jobs": { "description": "the page, newest first", "items": { "$ref": "#/components/schemas/Job" }, "type": "array" }, "next_cursor": { "oneOf": [ { "description": "the opaque cursor of the next page, absent when this page is the last", "type": "string" }, { "type": "null" } ] }, "summary": { "$ref": "#/components/schemas/JobsSummary" }, "total": { "description": "jobs of the tenant before filtering", "type": "integer" } }, "required": [ "jobs", "total", "summary", "next_cursor" ], "type": "object" }, "JobsSummary": { "additionalProperties": false, "description": "roll-up counts", "properties": { "failed": { "description": "failed jobs", "type": "integer" }, "passed": { "description": "passed jobs", "type": "integer" }, "queued": { "description": "queued jobs", "type": "integer" }, "running": { "description": "running jobs", "type": "integer" } }, "required": [ "queued", "running", "passed", "failed" ], "type": "object" }, "Lineage": { "additionalProperties": false, "description": "a lineage", "properties": { "bytes": { "description": "stored bytes", "type": "integer" }, "class": { "description": "the job class", "type": "string" }, "last_used_at": { "description": "last use, as RFC 3339", "type": "string" }, "lineage": { "description": "the lineage identity", "type": "string" }, "repository": { "description": "owner/name", "type": "string" } }, "required": [ "repository", "class", "lineage", "bytes", "last_used_at" ], "type": "object" }, "LocalDiffRequest": { "additionalProperties": true, "description": "the predecessor local diff form: repository, base_ref, fingerprint, base_commit, toolchain, toolchain_origin, tracked_diff and untracked_files", "type": "object" }, "Membership": { "additionalProperties": false, "description": "a tenant membership", "properties": { "organization_id": { "description": "the identity provider organization", "type": "string" }, "role": { "description": "the role in that tenant", "type": "string" }, "tenant": { "description": "the tenant", "type": "string" } }, "required": [ "tenant", "organization_id", "role" ], "type": "object" }, "Onboarding": { "additionalProperties": false, "description": "the onboarding state", "properties": { "claim_url": { "oneOf": [ { "description": "the provider-authorized claim route", "type": "string" }, { "type": "null" } ] }, "first_job": { "oneOf": [ { "$ref": "#/components/schemas/FirstJob" }, { "type": "null" } ] }, "install_url": { "oneOf": [ { "description": "the GitHub App installation link", "type": "string" }, { "type": "null" } ] }, "installation_active": { "oneOf": [ { "description": "whether the installation is claimed", "type": "boolean" }, { "type": "null" } ] }, "jobs_total": { "description": "jobs that have arrived", "type": "integer" } }, "required": [ "installation_active", "install_url", "claim_url", "jobs_total", "first_job" ], "type": "object" }, "OpenApiDocument": { "additionalProperties": true, "description": "the OpenAPI 3.1 document this build serves", "type": "object" }, "OperatingStates": { "additionalProperties": true, "description": "the four operating states, each with its computation instant, typed reason and deadline, and each host's capacity observation", "type": "object" }, "OperatorAnomalies": { "description": "queued flags", "items": { "$ref": "#/components/schemas/OperatorAnomaly" }, "type": "array" }, "OperatorAnomaly": { "additionalProperties": true, "description": "an anomaly flag with its evidence and disposition", "type": "object" }, "OperatorAudit": { "description": "audit entries", "items": { "additionalProperties": true, "description": "an operator audit entry", "type": "object" }, "type": "array" }, "PendingDevice": { "oneOf": [ { "additionalProperties": false, "description": "a pending device authorization", "properties": { "expires_at": { "description": "when the code expires, as RFC 3339", "type": "string" }, "requesting_host": { "description": "the host that started the flow", "type": "string" }, "user_code": { "description": "the user code", "type": "string" } }, "required": [ "user_code", "requesting_host", "expires_at" ], "type": "object" }, { "type": "null" } ] }, "Placements": { "description": "placement rows", "items": { "additionalProperties": true, "description": "a placement row", "type": "object" }, "type": "array" }, "PlatformAnomalies": { "description": "queued platform anomalies", "items": { "$ref": "#/components/schemas/PlatformAnomaly" }, "type": "array" }, "PlatformAnomaly": { "additionalProperties": true, "description": "a platform anomaly with the evidence that produced it, the recovery available for its host, that recovery's step ledger once one has begun, and its disposition", "type": "object" }, "PlatformAnomalyDispositionRequest": { "additionalProperties": true, "description": "the disposition an operator records on a platform anomaly", "type": "object" }, "PurgeReceipt": { "additionalProperties": false, "description": "a purged lineage", "properties": { "consequence": { "description": "what the purge did", "type": "string" }, "lineage": { "description": "the lineage", "type": "string" }, "purged_by": { "description": "the principal", "type": "string" } }, "required": [ "lineage", "consequence", "purged_by" ], "type": "object" }, "PurgeRequest": { "additionalProperties": false, "description": "a lineage purge", "properties": { "confirm": { "description": "the confirmation the surface states", "type": "string" }, "lineage": { "description": "the lineage identity", "type": "string" } }, "required": [ "lineage", "confirm" ], "type": "object" }, "ReceiptRead": { "additionalProperties": true, "description": "a finalized receipt page or its refusal", "type": "object" }, "ReconcileOutcome": { "additionalProperties": true, "description": "the reconciliation outcome", "type": "object" }, "ReconcileRequest": { "additionalProperties": true, "description": "the reconciliation category and mutation", "type": "object" }, "Refusal": { "additionalProperties": false, "description": "a typed refusal", "properties": { "code": { "description": "the refusal code the document declares", "type": "string" }, "current_version": { "description": "the version a stale settings write must re-read", "type": "integer" }, "detail": { "description": "what was refused, for a person or an agent to act on", "type": "string" }, "expired_at": { "description": "when the credential expired, as RFC 3339", "type": "string" }, "reset_at": { "description": "when a rate limit resets, as RFC 3339", "type": "string" }, "retry_after_seconds": { "description": "seconds until the limit resets", "type": "integer" }, "revoked_at": { "description": "when the credential was revoked, as RFC 3339", "type": "string" }, "role": { "description": "the role the operation requires", "type": "string" }, "scope": { "description": "a credential scope", "enum": [ "read", "submit", "settings", "credentials", "admin" ], "type": "string" }, "status": { "description": "the HTTP status", "type": "integer" } }, "required": [ "code", "status", "detail" ], "type": "object" }, "RegistryCredentialReceipt": { "additionalProperties": false, "description": "a replaced credential", "properties": { "registry": { "description": "the registry", "type": "string" }, "replaced_by": { "description": "the principal", "type": "string" }, "version": { "description": "the active version", "type": "integer" } }, "required": [ "registry", "version", "replaced_by" ], "type": "object" }, "RegistryCredentialReplacement": { "additionalProperties": false, "description": "a registry credential replacement", "properties": { "authorization": { "description": "the authorization value; never echoed", "type": "string" }, "confirm": { "description": "the confirmation the surface states", "type": "string" }, "registry": { "description": "the registry host", "type": "string" } }, "required": [ "registry", "authorization", "confirm" ], "type": "object" }, "RepositoriesPage": { "additionalProperties": false, "description": "a page of repositories", "properties": { "advisories": { "description": "live advisories", "items": { "$ref": "#/components/schemas/Advisory" }, "type": "array" }, "lineages": { "description": "the lineages of the repositories on the page", "items": { "$ref": "#/components/schemas/Lineage" }, "type": "array" }, "next_cursor": { "oneOf": [ { "description": "the opaque cursor of the next page, absent when this page is the last", "type": "string" }, { "type": "null" } ] }, "repositories": { "description": "the page", "items": { "$ref": "#/components/schemas/RepositoryTotal" }, "type": "array" }, "storage_quota_bytes": { "description": "the tenant's quota", "type": "integer" }, "total_bytes": { "description": "the tenant's stored bytes", "type": "integer" } }, "required": [ "repositories", "lineages", "total_bytes", "storage_quota_bytes", "advisories", "next_cursor" ], "type": "object" }, "RepositoryPage": { "additionalProperties": false, "description": "one repository", "properties": { "advisories": { "description": "its advisories", "items": { "$ref": "#/components/schemas/AdvisoryDetail" }, "type": "array" }, "lineages": { "description": "its lineages", "items": { "$ref": "#/components/schemas/Lineage" }, "type": "array" }, "repository": { "description": "owner/name", "type": "string" }, "storage_quota_bytes": { "description": "the tenant quota", "type": "integer" }, "total_bytes": { "description": "its stored bytes", "type": "integer" } }, "required": [ "repository", "lineages", "total_bytes", "storage_quota_bytes", "advisories" ], "type": "object" }, "RepositorySettings": { "additionalProperties": false, "description": "a repository's settings at a version", "properties": { "affected_tests": { "description": "affected-test selection", "type": "boolean" }, "changed_at": { "description": "when", "type": "string" }, "changed_by": { "description": "attribution", "type": "string" }, "effective": { "description": "when changes take effect on this runtime, naming any setting it does not apply", "type": "string" }, "injected": { "description": "the effective settings", "items": { "$ref": "#/components/schemas/Setting" }, "type": "array" }, "minimum_wall_clock_ceiling_seconds": { "description": "the documented minimum", "type": "integer" }, "platform_default_wall_clock_ceiling_seconds": { "description": "the platform default, which is also the maximum", "type": "integer" }, "repository": { "description": "owner/name", "type": "string" }, "total_injection_opt_out": { "description": "the total opt-out", "type": "boolean" }, "total_injection_opt_out_origin": { "description": "where the opt-out comes from", "type": "string" }, "version": { "description": "the version a write must name", "type": "integer" }, "wall_clock_ceiling": { "$ref": "#/components/schemas/Setting" }, "wall_clock_ceiling_origin": { "description": "platform default or dashboard repository setting", "type": "string" }, "wall_clock_ceiling_seconds": { "description": "the ceiling a job carries when its captured source pins none", "type": "integer" } }, "required": [ "repository", "version", "affected_tests", "total_injection_opt_out", "total_injection_opt_out_origin", "changed_by", "changed_at", "effective", "injected", "wall_clock_ceiling", "wall_clock_ceiling_seconds", "wall_clock_ceiling_origin", "minimum_wall_clock_ceiling_seconds", "platform_default_wall_clock_ceiling_seconds" ], "type": "object" }, "RepositoryTotal": { "additionalProperties": false, "description": "a repository's storage", "properties": { "repository": { "description": "owner/name", "type": "string" }, "total_bytes": { "description": "stored bytes", "type": "integer" } }, "required": [ "repository", "total_bytes" ], "type": "object" }, "RetryReceipt": { "additionalProperties": false, "description": "a linked retry", "properties": { "original": { "description": "the terminal job", "type": "string" }, "retry": { "description": "the fresh job", "type": "string" }, "submitted_by": { "description": "the principal", "type": "string" } }, "required": [ "original", "retry", "submitted_by" ], "type": "object" }, "RevocationReceipt": { "additionalProperties": false, "description": "a revoked token", "properties": { "id": { "description": "the token id", "type": "string" }, "revoked_at": { "description": "when, as RFC 3339", "type": "string" }, "revoked_by": { "description": "the principal", "type": "string" } }, "required": [ "id", "revoked_at", "revoked_by" ], "type": "object" }, "Scope": { "description": "a credential scope", "enum": [ "read", "submit", "settings", "credentials", "admin" ], "type": "string" }, "Setting": { "additionalProperties": false, "description": "an effective setting", "properties": { "changed_at": { "description": "when, or the origin's description", "type": "string" }, "changed_by": { "description": "attribution", "type": "string" }, "dashboard_overridden": { "description": "the pin file overrides the dashboard value", "type": "boolean" }, "dashboard_value": { "oneOf": [ { "description": "the dashboard record's value", "type": "string" }, { "type": "null" } ] }, "effective": { "description": "when the value takes effect: `jobs submitted after the change` where admission applies it, or `not applied:` and the reason where this runtime does not", "type": "string" }, "name": { "description": "the setting", "type": "string" }, "origin": { "description": "platform default, dashboard repository setting or in-repo pin file", "type": "string" }, "value": { "description": "the effective value", "type": "string" } }, "required": [ "name", "value", "origin", "changed_by", "changed_at", "effective", "dashboard_value", "dashboard_overridden" ], "type": "object" }, "SettingReceipt": { "additionalProperties": false, "description": "a written setting", "properties": { "changed_at": { "description": "when, as RFC 3339", "type": "string" }, "changed_by": { "description": "the principal", "type": "string" }, "effective": { "description": "when the written value takes effect: `jobs submitted after the change`, `next job` for a tenant setting, or `not applied:` and the reason", "type": "string" }, "name": { "description": "the setting", "type": "string" }, "value": { "description": "the value written", "type": "string" }, "version": { "description": "the version after the write", "type": "integer" } }, "required": [ "name", "value", "version", "changed_by", "changed_at", "effective" ], "type": "object" }, "SettingWrite": { "additionalProperties": false, "description": "one setting at an observed version", "properties": { "name": { "description": "the setting", "type": "string" }, "value": { "description": "the value", "type": "string" }, "version": { "description": "the version the caller observed", "type": "integer" } }, "required": [ "version", "name", "value" ], "type": "object" }, "SourceArchiveIdentity": { "additionalProperties": false, "description": "immutable source archive identity", "properties": { "archive_bytes": { "maximum": 1107296276, "minimum": 0, "type": "integer" }, "directories": { "maximum": 250000, "minimum": 0, "type": "integer" }, "entries": { "maximum": 250000, "minimum": 0, "type": "integer" }, "manifest_bytes": { "maximum": 33554432, "minimum": 0, "type": "integer" }, "manifest_sha256": { "items": { "maximum": 255, "minimum": 0, "type": "integer" }, "maxItems": 32, "minItems": 32, "type": "array" }, "schema_version": { "enum": [ 1 ], "type": "integer" }, "sha256": { "items": { "maximum": 255, "minimum": 0, "type": "integer" }, "maxItems": 32, "minItems": 32, "type": "array" }, "source_bytes": { "maximum": 1073741824, "minimum": 0, "type": "integer" } }, "required": [ "schema_version", "sha256", "archive_bytes", "source_bytes", "entries", "directories", "manifest_sha256", "manifest_bytes" ], "type": "object" }, "SourceCapabilities": { "additionalProperties": false, "description": "configured source protocol and independent limits", "properties": { "archive_schema_version": { "description": "archive schema version 1", "type": "integer" }, "chunk_bytes": { "description": "fixed chunk length except for the final part", "type": "integer" }, "directories_max": { "description": "maximum derived source directories", "type": "integer" }, "entries_max": { "description": "maximum source entries", "type": "integer" }, "manifest_bytes_max": { "description": "maximum canonical manifest bytes", "type": "integer" }, "source_bytes_max": { "description": "maximum regular-file bytes in one capture", "type": "integer" }, "streamed_submission_enabled": { "description": "execution support is composed; each invocation is checked again before admission", "type": "boolean" }, "submission_schema_version": { "description": "job submission schema version 2", "type": "integer" }, "upload_ttl_seconds": { "description": "original reservation lifetime before admission", "type": "integer" } }, "required": [ "archive_schema_version", "submission_schema_version", "streamed_submission_enabled", "source_bytes_max", "manifest_bytes_max", "entries_max", "directories_max", "chunk_bytes", "upload_ttl_seconds" ], "type": "object" }, "SourceChunk": { "description": "raw source chunk bytes; never JSON or base64", "format": "binary", "maxLength": 4194304, "type": "string" }, "SourceChunkStatus": { "additionalProperties": false, "description": "verified original chunk presence", "properties": { "present": { "description": "retained bytes match the expected digest", "type": "boolean" } }, "required": [ "present" ], "type": "object" }, "SourceReference": { "additionalProperties": false, "description": "source owned by an authenticated tenant and repository", "properties": { "identity": { "$ref": "#/components/schemas/SourceArchiveIdentity" }, "repository": { "description": "the onboarded repository", "type": "string" }, "tenant": { "description": "the authenticated tenant", "type": "string" }, "upload": { "description": "immutable original upload ID", "type": "string" } }, "required": [ "tenant", "repository", "upload", "identity" ], "type": "object" }, "SourceReservation": { "additionalProperties": false, "description": "reserve one source upload under its idempotency key", "properties": { "identity": { "$ref": "#/components/schemas/SourceArchiveIdentity" }, "repository": { "description": "the onboarded repository", "type": "string" } }, "required": [ "repository", "identity" ], "type": "object" }, "SourceUpload": { "additionalProperties": false, "description": "durable source upload state", "properties": { "created_at": { "description": "original reservation time, as RFC 3339", "type": "string" }, "expires_at": { "description": "unclaimed upload expiry, as RFC 3339", "type": "string" }, "job": { "oneOf": [ { "description": "original admitted job ID", "type": "string" }, { "type": "null" } ] }, "source": { "$ref": "#/components/schemas/SourceReference" }, "state": { "description": "source authority state", "enum": [ "uploading", "verified", "admitted", "reclaiming", "removed" ], "type": "string" } }, "required": [ "source", "created_at", "expires_at", "state", "job" ], "type": "object" }, "TenantControlUpdate": { "additionalProperties": false, "description": "a controls update; absent members keep their value", "properties": { "bandwidth_bytes_per_second": { "description": "the ceiling", "type": "integer" }, "concurrency_vcpus": { "description": "the ceiling", "type": "integer" }, "rate_card": { "oneOf": [ { "description": "cost per vcpu-second, or null to clear", "type": "string" }, { "type": "null" } ] }, "storage_quota_bytes": { "description": "the quota", "type": "integer" }, "suspended": { "description": "suspend intake", "type": "boolean" } }, "required": [], "type": "object" }, "TenantControls": { "additionalProperties": false, "description": "operator-set tenant controls", "properties": { "bandwidth_bytes_per_second": { "description": "the ceiling", "type": "integer" }, "concurrency_vcpus": { "description": "the ceiling", "type": "integer" }, "rate_card": { "oneOf": [ { "additionalProperties": true, "description": "the rate card", "type": "object" }, { "type": "null" } ] }, "storage_quota_bytes": { "description": "the quota", "type": "integer" }, "suspended": { "description": "intake suspended", "type": "boolean" } }, "required": [ "concurrency_vcpus", "storage_quota_bytes", "bandwidth_bytes_per_second", "rate_card", "suspended" ], "type": "object" }, "TenantId": { "description": "the tenant identifier", "type": "string" }, "TenantSettings": { "additionalProperties": false, "description": "the tenant policy and limits", "properties": { "active_vcpus": { "description": "vcpus in use", "type": "integer" }, "bandwidth_bytes_per_second": { "description": "current bandwidth", "type": "integer" }, "bandwidth_ceiling_bytes_per_second": { "description": "the operator-set ceiling", "type": "integer" }, "changed_at": { "description": "when, as RFC 3339", "type": "string" }, "changed_by": { "description": "attribution", "type": "string" }, "compile_cache_enabled": { "description": "the cold-path tenant compile cache, off by default", "type": "boolean" }, "concurrency_vcpus": { "description": "the operator-set ceiling", "type": "integer" }, "egress_allowlist": { "description": "allowed destinations", "items": { "description": "a host name or address", "type": "string" }, "type": "array" }, "egress_mode": { "description": "open or allowlist", "type": "string" }, "fork_pr_enabled": { "description": "fork pull requests enabled as one unit", "type": "boolean" }, "log_retention_days": { "description": "retention in days", "type": "integer" }, "storage_bytes": { "description": "stored bytes", "type": "integer" }, "storage_quota_bytes": { "description": "the operator-set quota", "type": "integer" }, "tenant": { "description": "the tenant", "type": "string" }, "version": { "description": "the version a write must name", "type": "integer" } }, "required": [ "tenant", "version", "egress_mode", "egress_allowlist", "fork_pr_enabled", "compile_cache_enabled", "log_retention_days", "changed_by", "changed_at", "active_vcpus", "concurrency_vcpus", "storage_bytes", "storage_quota_bytes", "bandwidth_bytes_per_second", "bandwidth_ceiling_bytes_per_second" ], "type": "object" }, "Token": { "additionalProperties": false, "description": "a device token", "properties": { "created_at": { "description": "creation, as RFC 3339", "type": "string" }, "id": { "description": "the token id", "type": "string" }, "last_used_at": { "description": "last use, or never", "type": "string" }, "revoked": { "description": "revoked", "type": "boolean" }, "role": { "description": "the role it carries", "type": "string" } }, "required": [ "id", "created_at", "last_used_at", "role", "revoked" ], "type": "object" }, "TokensPage": { "additionalProperties": false, "description": "a page of tokens", "properties": { "next_cursor": { "oneOf": [ { "description": "the opaque cursor of the next page, absent when this page is the last", "type": "string" }, { "type": "null" } ] }, "tokens": { "description": "the page", "items": { "$ref": "#/components/schemas/Token" }, "type": "array" } }, "required": [ "tokens", "next_cursor" ], "type": "object" }, "UndrainRequest": { "additionalProperties": false, "description": "an undrain at a policy revision", "properties": { "revision": { "description": "the revision observed", "type": "integer" } }, "required": [ "revision" ], "type": "object" }, "Usage": { "additionalProperties": false, "description": "the period's usage", "properties": { "cost": { "oneOf": [ { "description": "cost under the rate card", "type": "number" }, { "type": "null" } ] }, "days": { "description": "per day", "items": { "$ref": "#/components/schemas/UsageDay" }, "type": "array" }, "elapsed_seconds": { "description": "elapsed seconds", "type": "integer" }, "from": { "description": "the period start, as RFC 3339", "type": "string" }, "period": { "description": "YYYY-MM", "type": "string" }, "periods": { "description": "periods offered, newest first", "items": { "description": "YYYY-MM", "type": "string" }, "type": "array" }, "records": { "description": "per-second records in the period", "type": "integer" }, "repositories": { "description": "per repository", "items": { "$ref": "#/components/schemas/UsageRepository" }, "type": "array" }, "to": { "description": "the period end or the captured present, as RFC 3339", "type": "string" }, "vcpu_seconds": { "description": "vcpu seconds", "type": "integer" }, "vm_seconds": { "description": "vm seconds", "type": "integer" } }, "required": [ "period", "from", "to", "periods", "records", "days", "elapsed_seconds", "vm_seconds", "vcpu_seconds", "cost", "repositories" ], "type": "object" }, "UsageDay": { "additionalProperties": false, "description": "one day", "properties": { "date": { "description": "YYYY-MM-DD", "type": "string" }, "elapsed_seconds": { "description": "elapsed seconds", "type": "integer" }, "jobs": { "description": "jobs reaped that day", "type": "integer" }, "vcpu_seconds": { "description": "vcpu seconds", "type": "integer" }, "vm_seconds": { "description": "vm seconds", "type": "integer" } }, "required": [ "date", "jobs", "elapsed_seconds", "vm_seconds", "vcpu_seconds" ], "type": "object" }, "UsageExport": { "additionalProperties": false, "description": "the period's records", "properties": { "adjustments": { "description": "adjustments", "items": { "additionalProperties": true, "description": "a usage adjustment", "type": "object" }, "type": "array" }, "displayed_totals": { "$ref": "#/components/schemas/UsageTotals" }, "from": { "description": "the period start, as RFC 3339", "type": "string" }, "period": { "description": "YYYY-MM", "type": "string" }, "records": { "description": "per-second usage records", "items": { "additionalProperties": true, "description": "a usage record", "type": "object" }, "type": "array" }, "tenant": { "description": "the tenant", "type": "string" }, "to": { "description": "the period end, as RFC 3339", "type": "string" }, "totals": { "additionalProperties": true, "description": "summed record totals", "type": "object" } }, "required": [ "tenant", "period", "from", "to", "records", "adjustments", "totals", "displayed_totals" ], "type": "object" }, "UsageJobClass": { "additionalProperties": false, "description": "one job class", "properties": { "cost": { "oneOf": [ { "description": "cost under the rate card", "type": "number" }, { "type": "null" } ] }, "elapsed_seconds": { "description": "elapsed seconds", "type": "integer" }, "job_class": { "description": "the class", "type": "string" }, "vcpu_seconds": { "description": "vcpu seconds", "type": "integer" }, "vm_seconds": { "description": "vm seconds", "type": "integer" } }, "required": [ "job_class", "elapsed_seconds", "vm_seconds", "vcpu_seconds", "cost" ], "type": "object" }, "UsageRepository": { "additionalProperties": false, "description": "one repository", "properties": { "cost": { "oneOf": [ { "description": "cost under the rate card", "type": "number" }, { "type": "null" } ] }, "cost_per_merged_pr": { "oneOf": [ { "description": "cost per merged pull request", "type": "number" }, { "type": "null" } ] }, "elapsed_seconds": { "description": "elapsed seconds", "type": "integer" }, "job_classes": { "description": "per class", "items": { "$ref": "#/components/schemas/UsageJobClass" }, "type": "array" }, "merged_pull_requests": { "description": "merged pull requests in the period", "type": "integer" }, "repository": { "description": "owner/name", "type": "string" }, "vcpu_seconds": { "description": "vcpu seconds", "type": "integer" }, "vm_seconds": { "description": "vm seconds", "type": "integer" } }, "required": [ "repository", "elapsed_seconds", "vm_seconds", "vcpu_seconds", "cost", "merged_pull_requests", "cost_per_merged_pr", "job_classes" ], "type": "object" }, "UsageTotals": { "additionalProperties": false, "description": "displayed totals", "properties": { "cost": { "oneOf": [ { "description": "cost under the rate card", "type": "number" }, { "type": "null" } ] }, "elapsed_seconds": { "description": "elapsed seconds", "type": "integer" }, "vcpu_seconds": { "description": "vcpu seconds", "type": "integer" }, "vm_seconds": { "description": "vm seconds", "type": "integer" } }, "required": [ "elapsed_seconds", "vm_seconds", "vcpu_seconds", "cost" ], "type": "object" } }, "securitySchemes": { "dashboard_session": { "description": "the signed-in dashboard session; a person's role maps onto scopes", "in": "cookie", "name": "lathe_session", "type": "apiKey" }, "operator_bootstrap": { "description": "the operator bootstrap credential, presented once to open an operator session", "scheme": "bearer", "type": "http" }, "operator_session": { "description": "an operator session; unreachable from every tenant credential, which answers not found", "in": "cookie", "name": "lathe_operator_session", "type": "apiKey" }, "tenant_credential": { "description": "a CLI device token (lathe_cli_...) or an agent credential (lathe_agent_...); the operation names the scope the credential must hold", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Every operation a signed-in person can perform in the dashboard is an operation of this document. Tenant credentials (device tokens and agent credentials) call the customer operations within their scopes; the operator identity calls the operator operations. Every customer mutation requires an idempotency-key header and replays the original receipt for the same key and body; every list pages by an opaque cursor in a stable order; every refusal is a typed document naming its code.", "summary": "the lathe customer and operator operation catalogue", "title": "lathe", "version": "1" }, "openapi": "3.1.0", "paths": { "/api/audit": { "get": { "description": "Attributed management mutations of the tenant, newest first, paged by cursor.", "operationId": "audit.list", "parameters": [ { "description": "the opaque cursor a previous page returned; absent starts at the newest row", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "rows per page, 1 to 1000; the default is 200", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditPage" } } }, "description": "list tenant audit entries" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "list tenant audit entries", "tags": [ "audit" ], "x-lathe-cli": { "command": "cargo lathe audit list", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "audit_list", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "invalid_request" ], "x-lathe-scope": "read" } }, "/api/cli/events": { "get": { "description": "Tenant job status events as server-sent events, resumable from a durable sequence.", "operationId": "cli.events", "parameters": [ { "description": "the durable sequence already observed", "in": "query", "name": "after", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } } }, "description": "stream tenant job events; server-sent events" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "stream tenant job events", "tags": [ "cli" ], "x-lathe-cli": { "command": "cargo lathe status", "generated": false }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "invalid_request" ], "x-lathe-scope": "read" } }, "/api/cli/tenant": { "get": { "description": "The tenant the credential is bound to.", "operationId": "cli.tenant", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantId" } } }, "description": "the credential's tenant" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "the credential's tenant", "tags": [ "cli" ], "x-lathe-cli": { "command": "cargo lathe tenant", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "cli_tenant", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable" ], "x-lathe-scope": "read" } }, "/api/cli/tokens": { "get": { "description": "The calling person's device tokens with creation, last use and revocation, paged by cursor. Tokens belong to people; an agent credential is refused.", "operationId": "cli_tokens.list", "parameters": [ { "description": "the opaque cursor a previous page returned; absent starts at the newest row", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "rows per page, 1 to 1000; the default is 200", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokensPage" } } }, "description": "list the caller's CLI tokens" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required", "human_principal_required" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "list the caller's CLI tokens", "tags": [ "cli_tokens" ], "x-lathe-cli": { "command": "cargo lathe tokens list", "generated": true }, "x-lathe-human-only": true, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "human_principal_required", "invalid_request" ], "x-lathe-scope": "credentials" } }, "/api/cli/tokens/{id}/revocation": { "post": { "description": "Revoke one of the caller's device tokens; the next request presenting it is refused.", "operationId": "cli_tokens.revoke", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevocationReceipt" } } }, "description": "revoke a CLI token" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_required" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required", "human_principal_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "revoke a CLI token", "tags": [ "cli_tokens" ], "x-lathe-cli": { "command": "cargo lathe tokens revoke", "generated": true }, "x-lathe-human-only": true, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight", "human_principal_required", "not_found" ], "x-lathe-scope": "credentials" } }, "/api/credentials": { "get": { "description": "The tenant's agent credentials with name, scopes, expiry, last use and revocation, paged by cursor.", "operationId": "credentials.list", "parameters": [ { "description": "the opaque cursor a previous page returned; absent starts at the newest row", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "rows per page, 1 to 1000; the default is 200", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialsPage" } } }, "description": "list agent credentials" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "list agent credentials", "tags": [ "credentials" ], "x-lathe-cli": { "command": "cargo lathe credential list", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "credentials_list", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "invalid_request" ], "x-lathe-scope": "credentials" }, "post": { "description": "Mint a named, scoped, expiring agent credential. The value is shown once. A human admin performs this; no agent credential mints another.", "operationId": "credentials.create", "parameters": [ { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialIssued" } } }, "description": "mint an agent credential" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_required", "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required", "human_principal_required" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight", "conflict" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "mint an agent credential", "tags": [ "credentials" ], "x-lathe-cli": { "command": "cargo lathe credential create", "generated": false }, "x-lathe-human-only": true, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight", "human_principal_required", "invalid_request", "conflict" ], "x-lathe-scope": "admin" } }, "/api/credentials/{name}/revocation": { "post": { "description": "Revoke a credential by name; its next use is refused as revoked.", "operationId": "credentials.revoke", "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRevocationReceipt" } } }, "description": "revoke an agent credential" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_required" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "revoke an agent credential", "tags": [ "credentials" ], "x-lathe-cli": { "command": "cargo lathe credential revoke", "generated": true }, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": "credentials_revoke", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight", "not_found" ], "x-lathe-scope": "credentials" } }, "/api/device/approve": { "post": { "description": "Approve a pending device code. Only a signed-in human session performs this; no credential, scope or other operation approves a device code.", "operationId": "device.approve", "parameters": [ { "description": "the user code to approve", "in": "query", "name": "user_code", "required": true, "schema": { "type": "string" } }, { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceApprovalReceipt" } } }, "description": "approve a device code" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request", "idempotency_key_required" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "session_required" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight" ] } }, "security": [ { "dashboard_session": [] } ], "summary": "approve a device code", "tags": [ "device" ], "x-lathe-cli": { "command": null, "reason": "device approval is a human act inside a signed-in session" }, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "session_required", "invalid_request", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight" ] } }, "/api/device/pending": { "get": { "description": "The pending device authorization for a user code, for the approval page inside a signed-in session.", "operationId": "device.pending", "parameters": [ { "description": "the user code the CLI printed", "in": "query", "name": "user_code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingDevice" } } }, "description": "read a pending device code" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "session_required" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "dashboard_session": [] } ], "summary": "read a pending device code", "tags": [ "device" ], "x-lathe-cli": { "command": null, "reason": "the approval page is a human surface inside a signed-in session" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "session_required", "unavailable" ] } }, "/api/device/poll": { "get": { "description": "Poll the device flow until a person approves the code; an approved poll issues the device token once.", "operationId": "device.poll", "parameters": [ { "description": "the device code the start answered with", "in": "query", "name": "device_code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicePoll" } } }, "description": "poll a device authorization" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [], "summary": "poll a device authorization", "tags": [ "device" ], "x-lathe-cli": { "command": "cargo lathe login", "generated": false }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "rate_limited", "unavailable" ] } }, "/api/device/start": { "post": { "description": "Begin the CLI device flow. The answer names the approval page and the user code a signed-in person confirms there.", "operationId": "device.start", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorization" } } }, "description": "start a device authorization" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "upstream_failed" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [], "summary": "start a device authorization", "tags": [ "device" ], "x-lathe-cli": { "command": "cargo lathe login", "generated": false }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "rate_limited", "upstream_failed", "unavailable" ] } }, "/api/events": { "get": { "description": "Job transitions for the signed-in session's tenant as server-sent events; hints the dashboard reconciles against authoritative reads.", "operationId": "events.stream", "parameters": [], "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } } }, "description": "stream dashboard hints; server-sent events" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "session_required" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] } }, "security": [ { "dashboard_session": [] } ], "summary": "stream dashboard hints", "tags": [ "events" ], "x-lathe-cli": { "command": null, "reason": "the dashboard hint stream is a browser session surface; the CLI reads the tenant event stream" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "session_required", "rate_limited" ] } }, "/api/identity": { "get": { "description": "The principal the credential or session resolves to: a person with role and memberships, or an agent with its scopes.", "operationId": "identity.current", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identity" } } }, "description": "the calling principal" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "the calling principal", "tags": [ "identity" ], "x-lathe-cli": { "command": "cargo lathe whoami", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "identity_current", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable" ], "x-lathe-scope": "read" } }, "/api/jobs": { "get": { "description": "Jobs of the active tenant, newest first, filtered and paged by an opaque cursor in a stable order.", "operationId": "jobs.list", "parameters": [ { "description": "only jobs of this owner/name repository", "in": "query", "name": "repository", "required": false, "schema": { "type": "string" } }, { "description": "only jobs of this branch", "in": "query", "name": "branch", "required": false, "schema": { "type": "string" } }, { "description": "only jobs in this status", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "description": "only jobs of this class", "in": "query", "name": "class", "required": false, "schema": { "type": "string" } }, { "description": "the opaque cursor a previous page returned; absent starts at the newest row", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "rows per page, 1 to 1000; the default is 200", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobsPage" } } }, "description": "list jobs" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "list jobs", "tags": [ "jobs" ], "x-lathe-cli": { "command": "cargo lathe jobs list", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "jobs_list", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "invalid_request" ], "x-lathe-scope": "read" }, "post": { "deprecated": true, "description": "A retained predecessor route. The attempt runtime refuses it and names the captured Cargo workspace submission; new clients do not call it.", "operationId": "jobs.submit_diff", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalDiffRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobId" } } }, "description": "submit a local diff (predecessor)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request", "idempotency_key_required" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "legacy_unsupported" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "submit a local diff (predecessor)", "tags": [ "jobs" ], "x-lathe-cli": { "command": null, "reason": "a retained predecessor route; the CLI submits captured Cargo workspaces" }, "x-lathe-idempotency": "legacy", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "invalid_request", "not_found", "conflict", "legacy_unsupported", "idempotency_key_required" ], "x-lathe-scope": "submit" } }, "/api/jobs/{id}": { "get": { "description": "The authoritative job record.", "operationId": "jobs.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } }, "description": "read a job" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "read a job", "tags": [ "jobs" ], "x-lathe-cli": { "command": "cargo lathe jobs get", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "jobs_get", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "not_found" ], "x-lathe-scope": "read" } }, "/api/jobs/{id}/artifacts": { "get": { "description": "The published artifact inventory of a job.", "operationId": "jobs.artifacts", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactInventory" } } }, "description": "list a job's artifacts" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "gone" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "list a job's artifacts", "tags": [ "jobs" ], "x-lathe-cli": { "command": "cargo lathe artifacts", "generated": false }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "jobs_artifacts", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "not_found", "gone" ], "x-lathe-scope": "read" } }, "/api/jobs/{id}/artifacts/{attempt}/{index}": { "get": { "description": "One published artifact file as bytes.", "operationId": "jobs.artifact_bytes", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "attempt", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "download an artifact; bytes" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "gone" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "download an artifact", "tags": [ "jobs" ], "x-lathe-cli": { "command": "cargo lathe artifacts", "generated": false }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "not_found", "gone" ], "x-lathe-scope": "read" } }, "/api/jobs/{id}/attempts/{attempt}/cargo-output": { "get": { "description": "The retained Cargo output of one attempt as bytes.", "operationId": "jobs.cargo_output", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "attempt", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "download an attempt's Cargo output; bytes" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "download an attempt's Cargo output", "tags": [ "jobs" ], "x-lathe-cli": { "command": "cargo lathe logs", "generated": false }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "not_found" ], "x-lathe-scope": "read" } }, "/api/jobs/{id}/cancel": { "post": { "description": "Request cancellation; running units are reaped and metering closes.", "operationId": "jobs.cancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancellationReceipt" } } }, "description": "cancel a job" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_required" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight", "conflict" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "upstream_failed" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "cancel a job", "tags": [ "jobs" ], "x-lathe-cli": { "command": "cargo lathe cancel", "generated": false }, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": "jobs_cancel", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight", "not_found", "conflict", "upstream_failed" ], "x-lathe-scope": "submit" } }, "/api/jobs/{id}/evidence": { "get": { "description": "The job, its evidence report, its usage record and, paged by cursor, its attempt evidence.", "operationId": "jobs.evidence", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "the attempt evidence cursor a previous page returned", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEvidence" } } }, "description": "read a job's evidence" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "read a job's evidence", "tags": [ "jobs" ], "x-lathe-cli": { "command": "cargo lathe jobs evidence", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "jobs_evidence", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "not_found", "invalid_request" ], "x-lathe-scope": "read" } }, "/api/jobs/{id}/logs": { "get": { "description": "One page of durable job log records from a cursor.", "operationId": "jobs.logs", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "the log cursor a previous page returned", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "records per page; the default is 100", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobLogPage" } } }, "description": "read a page of job logs" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] }, { "dashboard_session": [] } ], "summary": "read a page of job logs", "tags": [ "jobs" ], "x-lathe-browser-session": true, "x-lathe-cli": { "command": "cargo lathe logs", "generated": false }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "jobs_logs", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "not_found", "invalid_request" ], "x-lathe-scope": "read" } }, "/api/jobs/{id}/logs/stream": { "get": { "description": "Job log pages as server-sent events from a cursor until the job settles.", "operationId": "jobs.logs_stream", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "the log cursor to resume from", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "records per page", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } } }, "description": "stream job logs; server-sent events" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] }, { "dashboard_session": [] } ], "summary": "stream job logs", "tags": [ "jobs" ], "x-lathe-browser-session": true, "x-lathe-cli": { "command": "cargo lathe logs", "generated": false }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "not_found", "invalid_request" ], "x-lathe-scope": "read" } }, "/api/jobs/{id}/retry": { "post": { "description": "Submit a fresh job linked to a terminal original.", "operationId": "jobs.retry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryReceipt" } } }, "description": "retry a terminal job" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_required" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight", "conflict" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "retry a terminal job", "tags": [ "jobs" ], "x-lathe-cli": { "command": "cargo lathe jobs retry", "generated": true }, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": "jobs_retry", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight", "not_found", "conflict" ], "x-lathe-scope": "submit" } }, "/api/onboarding": { "get": { "description": "Whether the GitHub App installation is claimed, the installation and claim links, and whether a job has arrived.", "operationId": "onboarding.surface", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Onboarding" } } }, "description": "the onboarding state" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "the onboarding state", "tags": [ "onboarding" ], "x-lathe-cli": { "command": "cargo lathe onboarding status", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "onboarding_surface", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable" ], "x-lathe-scope": "read" } }, "/api/onboarding/claims": { "post": { "description": "Link an installation to the active tenant. Requires the admin scope; the claim is attributed to the caller.", "operationId": "onboarding.claim", "parameters": [ { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimReceipt" } } }, "description": "claim a GitHub App installation" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_required", "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight", "conflict" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "upstream_failed" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "claim a GitHub App installation", "tags": [ "onboarding" ], "x-lathe-cli": { "command": "cargo lathe onboarding claim", "generated": true }, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": "onboarding_claim", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight", "invalid_request", "conflict", "upstream_failed" ], "x-lathe-scope": "admin" } }, "/api/openapi.json": { "get": { "description": "The document this build serves, generated from the catalogue that also binds the routes.", "operationId": "openapi.document", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" } } }, "description": "the served OpenAPI document" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [], "summary": "the served OpenAPI document", "tags": [ "openapi" ], "x-lathe-cli": { "command": "cargo lathe openapi", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unavailable" ] } }, "/api/repositories": { "get": { "description": "Onboarded repositories with their lineage storage, the tenant quota and live advisories, paged by cursor.", "operationId": "repositories.list", "parameters": [ { "description": "the opaque cursor a previous page returned; absent starts at the newest row", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "rows per page, 1 to 1000; the default is 200", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoriesPage" } } }, "description": "list repositories" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "list repositories", "tags": [ "repositories" ], "x-lathe-cli": { "command": "cargo lathe repositories list", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "repositories_list", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "invalid_request" ], "x-lathe-scope": "read" } }, "/api/repositories/{owner}/{name}": { "get": { "description": "One repository: its lineages by class against the quota and its advisories with their measured basis.", "operationId": "repositories.get", "parameters": [ { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryPage" } } }, "description": "read a repository" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "read a repository", "tags": [ "repositories" ], "x-lathe-cli": { "command": "cargo lathe repositories get", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "repositories_get", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "not_found" ], "x-lathe-scope": "read" } }, "/api/repositories/{owner}/{name}/admission": { "get": { "description": "Confirm the repository is onboarded and resolve the merge base of a base ref before a local submission.", "operationId": "repositories.admission", "parameters": [ { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "the base ref to resolve", "in": "query", "name": "base_ref", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Admission" } } }, "description": "resolve a repository's merge base" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "upstream_failed" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "resolve a repository's merge base", "tags": [ "repositories" ], "x-lathe-cli": { "command": "cargo lathe repositories admission", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "repositories_admission", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "not_found", "upstream_failed" ], "x-lathe-scope": "submit" } }, "/api/repositories/{owner}/{name}/advisories/{advisory}/dismissal": { "post": { "description": "Dismiss a repository advisory; the dismissal is remembered and attributed.", "operationId": "repositories.advisories.dismiss", "parameters": [ { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "advisory", "required": true, "schema": { "type": "string" } }, { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DismissalReceipt" } } }, "description": "dismiss an advisory" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_required" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "dismiss an advisory", "tags": [ "repositories" ], "x-lathe-cli": { "command": "cargo lathe repositories advisories dismiss", "generated": true }, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": "repositories_advisories_dismiss", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight", "not_found" ], "x-lathe-scope": "settings" } }, "/api/repositories/{owner}/{name}/purges": { "post": { "description": "Delete a lineage so the next matching job starts cold. The request carries the confirmation the consequence requires.", "operationId": "repositories.lineages.purge", "parameters": [ { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurgeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurgeReceipt" } } }, "description": "purge a lineage" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_required", "confirmation_required", "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "purge a lineage", "tags": [ "repositories" ], "x-lathe-cli": { "command": "cargo lathe repositories lineages purge", "generated": true }, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": "repositories_lineages_purge", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight", "confirmation_required", "not_found", "invalid_request" ], "x-lathe-scope": "admin" } }, "/api/repositories/{owner}/{name}/settings": { "get": { "description": "The repository's build settings with their version, effective origin and attribution and when each takes effect, and the wall-clock ceiling a job for it carries with the documented bounds. Admission snapshots the settings for each submitted job; a build setting the repository's own Cargo configuration already sets is reported in the job's evidence as not applied, never replaced. The read requires the member role a submission requires and has no lifecycle effect, so a client that bounds a job's cost reads it before it submits.", "operationId": "repositories.settings.get", "parameters": [ { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositorySettings" } } }, "description": "read repository settings" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "read repository settings", "tags": [ "repositories" ], "x-lathe-cli": { "command": "cargo lathe repositories settings get", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "repositories_settings_get", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "not_found" ], "x-lathe-scope": "submit" }, "post": { "description": "Write one setting at the version the caller observed; a moved version is refused naming the current one. The receipt states when the value takes effect.", "operationId": "repositories.settings.write", "parameters": [ { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingWrite" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingReceipt" } } }, "description": "write a repository setting" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_required", "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight", "stale_version" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "write a repository setting", "tags": [ "repositories" ], "x-lathe-cli": { "command": "cargo lathe repositories settings set", "generated": true }, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": "repositories_settings_write", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight", "invalid_request", "stale_version" ], "x-lathe-scope": "settings" } }, "/api/source-capabilities": { "get": { "description": "Read source protocol versions and independent limits before capturing or uploading a workspace. Configured streamed submission still requires per-invocation execution checks and available capacity.", "operationId": "sources.capabilities", "parameters": [ { "description": "the authorized repository owning this upload", "in": "query", "name": "repository", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceCapabilities" } } }, "description": "read source transport capabilities" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "read source transport capabilities", "tags": [ "sources" ], "x-lathe-cli": { "command": "cargo lathe test", "generated": false }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "invalid_request", "not_found" ], "x-lathe-scope": "submit" } }, "/api/sources": { "post": { "description": "Reserve immutable source identity for an onboarded repository. The idempotency-key is the upload ID and remains bound to these exact inputs.", "operationId": "sources.reserve", "parameters": [ { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceReservation" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceUpload" } } }, "description": "reserve captured source" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_required", "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight", "conflict" ] }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "gone" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "reserve captured source", "tags": [ "sources" ], "x-lathe-cli": { "command": "cargo lathe test", "generated": false }, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight", "invalid_request", "not_found", "gone", "conflict" ], "x-lathe-scope": "submit" } }, "/api/sources/{upload}": { "get": { "description": "Read the original tenant and repository bound upload, including expiry and retained admission state.", "operationId": "sources.status", "parameters": [ { "in": "path", "name": "upload", "required": true, "schema": { "type": "string" } }, { "description": "the authorized repository owning this upload", "in": "query", "name": "repository", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceUpload" } } }, "description": "read source upload status" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "read source upload status", "tags": [ "sources" ], "x-lathe-cli": { "command": "cargo lathe test", "generated": false }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "invalid_request", "not_found" ], "x-lathe-scope": "submit" } }, "/api/sources/{upload}/chunks/{part}": { "get": { "description": "Verify a retained chunk against the caller's SHA-256 before resuming. An absent chunk reports present=false; changed bytes conflict.", "operationId": "sources.chunk.check", "parameters": [ { "in": "path", "name": "upload", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "part", "required": true, "schema": { "type": "string" } }, { "description": "the authorized repository owning this upload", "in": "query", "name": "repository", "required": true, "schema": { "type": "string" } }, { "description": "64 lowercase hexadecimal SHA-256 digits", "in": "query", "name": "sha256", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceChunkStatus" } } }, "description": "verify a retained source chunk" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "gone" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "verify a retained source chunk", "tags": [ "sources" ], "x-lathe-cli": { "command": "cargo lathe test", "generated": false }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "invalid_request", "not_found", "gone", "conflict" ], "x-lathe-scope": "submit" }, "post": { "description": "Upload one raw source chunk, at most 4194304 bytes. Repeat bytes verify the original chunk; changed bytes conflict. The idempotency-key must equal the upload ID.", "operationId": "sources.chunk.put", "parameters": [ { "in": "path", "name": "upload", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "part", "required": true, "schema": { "type": "string" } }, { "description": "the authorized repository owning this upload", "in": "query", "name": "repository", "required": true, "schema": { "type": "string" } }, { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/SourceChunk" } } }, "required": true }, "responses": { "204": { "description": "upload an immutable source chunk" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_required", "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight", "conflict" ] }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "gone" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "upload an immutable source chunk", "tags": [ "sources" ], "x-lathe-cli": { "command": "cargo lathe test", "generated": false }, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight", "invalid_request", "not_found", "gone", "conflict" ], "x-lathe-scope": "submit" } }, "/api/sources/{upload}/complete": { "post": { "description": "Verify every archive byte and manifest rule before source can authorize admission. The idempotency-key must equal the upload ID; repeated completion preserves the original owner.", "operationId": "sources.complete", "parameters": [ { "in": "path", "name": "upload", "required": true, "schema": { "type": "string" } }, { "description": "the authorized repository owning this upload", "in": "query", "name": "repository", "required": true, "schema": { "type": "string" } }, { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceUpload" } } }, "description": "verify completed source" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_required", "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight", "conflict" ] }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "gone" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "verify completed source", "tags": [ "sources" ], "x-lathe-cli": { "command": "cargo lathe test", "generated": false }, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight", "invalid_request", "not_found", "gone", "conflict" ], "x-lathe-scope": "submit" } }, "/api/tenant/registry-credentials": { "post": { "description": "Replace a registry credential on every host, removing the prior value once every host acknowledges. The request carries the confirmation.", "operationId": "tenant.registry_credential.replace", "parameters": [ { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryCredentialReplacement" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryCredentialReceipt" } } }, "description": "replace a private registry credential" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_required", "confirmation_required", "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "upstream_failed" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "replace a private registry credential", "tags": [ "tenant" ], "x-lathe-cli": { "command": "cargo lathe registry-credential replace", "generated": true }, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": "tenant_registry_credential_replace", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight", "confirmation_required", "invalid_request", "upstream_failed" ], "x-lathe-scope": "credentials" } }, "/api/tenant/settings": { "get": { "description": "The tenant policy with its version and attribution, and the operator-set limits beside current consumption.", "operationId": "tenant.settings.get", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantSettings" } } }, "description": "read tenant settings" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "read tenant settings", "tags": [ "tenant" ], "x-lathe-cli": { "command": "cargo lathe settings get", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "tenant_settings_get", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable" ], "x-lathe-scope": "read" }, "post": { "description": "Write one tenant-editable setting at the version the caller observed. Operator-controlled settings are refused and the refusal is audited.", "operationId": "tenant.settings.write", "parameters": [ { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingWrite" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingReceipt" } } }, "description": "write a tenant setting" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_required", "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required", "operator_controlled" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight", "stale_version" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "write a tenant setting", "tags": [ "tenant" ], "x-lathe-cli": { "command": "cargo lathe settings set", "generated": true }, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": "tenant_settings_write", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight", "invalid_request", "stale_version", "operator_controlled" ], "x-lathe-scope": "settings" } }, "/api/usage": { "get": { "description": "The period's usage rolled up from per-second records, per day and per repository, with the rate card where one is set.", "operationId": "usage.report", "parameters": [ { "description": "the period as YYYY-MM; absent means the current month", "in": "query", "name": "period", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } }, "description": "read the usage report" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "read the usage report", "tags": [ "usage" ], "x-lathe-cli": { "command": "cargo lathe usage report", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "usage_report", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "invalid_request" ], "x-lathe-scope": "read" } }, "/api/usage/export": { "get": { "description": "The period's per-second records and adjustments as a document whose totals equal the report.", "operationId": "usage.export", "parameters": [ { "description": "the period as YYYY-MM; absent means the current month", "in": "query", "name": "period", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageExport" } } }, "description": "export the period's records" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] }, { "dashboard_session": [] } ], "summary": "export the period's records", "tags": [ "usage" ], "x-lathe-browser-session": true, "x-lathe-cli": { "command": "cargo lathe usage export", "generated": true }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": "usage_export", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "invalid_request" ], "x-lathe-scope": "read" } }, "/api/v2/jobs": { "post": { "deprecated": true, "description": "A retained predecessor route. The attempt runtime refuses it and names the captured Cargo workspace submission; new clients do not call it.", "operationId": "jobs.submit_diff_v2", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalDiffRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobId" } } }, "description": "submit a local diff with artifacts (predecessor)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request", "idempotency_key_required" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "legacy_unsupported" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "submit a local diff with artifacts (predecessor)", "tags": [ "jobs" ], "x-lathe-cli": { "command": null, "reason": "a retained predecessor route; the CLI submits captured Cargo workspaces" }, "x-lathe-idempotency": "legacy", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "invalid_request", "not_found", "conflict", "legacy_unsupported", "idempotency_key_required" ], "x-lathe-scope": "submit" } }, "/api/v3/jobs": { "post": { "deprecated": true, "description": "A retained predecessor route. The attempt runtime refuses it and names the captured Cargo workspace submission; new clients do not call it.", "operationId": "jobs.submit_diff_keyed", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalDiffRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobId" } } }, "description": "submit a local diff with an idempotency-key (predecessor)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request", "idempotency_key_required" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "legacy_unsupported" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "submit a local diff with an idempotency-key (predecessor)", "tags": [ "jobs" ], "x-lathe-cli": { "command": null, "reason": "a retained predecessor route; the CLI submits captured Cargo workspaces" }, "x-lathe-idempotency": "legacy", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "invalid_request", "not_found", "conflict", "legacy_unsupported", "idempotency_key_required" ], "x-lathe-scope": "submit" } }, "/api/v4/jobs": { "post": { "description": "Submit a captured Cargo workspace for check, build or test. The idempotency-key is the submission identity: a replay with the same key and body answers the original job.", "operationId": "jobs.submit", "parameters": [ { "description": "the caller's key for this mutation; a replay with the same key and body answers the original receipt within the retention window", "in": "header", "name": "idempotency-key", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CargoWorkspaceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobId" } } }, "description": "submit a captured Cargo workspace" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_required", "invalid_request" ] }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unauthenticated", "credential_revoked", "credential_expired" ] }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "out_of_scope", "role_required" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "idempotency_key_reused", "idempotency_key_in_flight", "conflict" ] }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "gone" ] }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "rate_limited" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "tenant_credential": [] } ], "summary": "submit a captured Cargo workspace", "tags": [ "jobs" ], "x-lathe-cli": { "command": "cargo lathe test", "generated": false }, "x-lathe-idempotency": "key", "x-lathe-mcp-tool": "jobs_submit", "x-lathe-refusals": [ "unauthenticated", "credential_revoked", "credential_expired", "out_of_scope", "role_required", "rate_limited", "unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_key_in_flight", "invalid_request", "not_found", "conflict", "gone" ], "x-lathe-scope": "submit" } }, "/operator/api/anomalies": { "get": { "description": "Queued usage anomaly flags with their evidence.", "operationId": "operator.anomalies.list", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorAnomalies" } } }, "description": "list anomaly flags" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "list anomaly flags", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] } }, "/operator/api/anomalies/platform": { "get": { "description": "Queued host silence and stalled launches with the evidence that produced each, the recovery available for the host, and that recovery's step ledger once one has begun.", "operationId": "operator.anomalies.platform.list", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAnomalies" } } }, "description": "list platform anomalies" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "list platform anomalies", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] } }, "/operator/api/anomalies/platform/{id}/disposition": { "post": { "description": "Record the disposition of a platform anomaly, attributed to the operator. It changes no job, attempt, host or admission.", "operationId": "operator.anomalies.platform.disposition", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAnomalyDispositionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAnomaly" } } }, "description": "record a platform anomaly disposition" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "record a platform anomaly disposition", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request" ] } }, "/operator/api/anomalies/{id}/disposition": { "post": { "description": "Record the disposition of an anomaly flag, attributed to the operator.", "operationId": "operator.anomalies.disposition", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlagDispositionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorAnomaly" } } }, "description": "record a flag disposition" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "record a flag disposition", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request" ] } }, "/operator/api/audit": { "get": { "description": "The operator audit trail.", "operationId": "operator.audit.list", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorAudit" } } }, "description": "list the operator audit" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "list the operator audit", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] } }, "/operator/api/audit/export": { "get": { "description": "The operator audit trail as a document.", "operationId": "operator.audit.export", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorAudit" } } }, "description": "export the operator audit" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "export the operator audit", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] } }, "/operator/api/audit/{sequence}": { "delete": { "description": "Every attempt to delete an audit entry is refused and itself audited.", "operationId": "operator.audit.refuse_delete", "parameters": [ { "in": "path", "name": "sequence", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditRefusal" } } }, "description": "refuse an audit deletion" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "refuse an audit deletion", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "conflict" ] }, "patch": { "description": "Every attempt to edit an audit entry is refused and itself audited.", "operationId": "operator.audit.refuse_patch", "parameters": [ { "in": "path", "name": "sequence", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditRefusal" } } }, "description": "refuse an audit edit" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "refuse an audit edit", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "conflict" ] } }, "/operator/api/canaries/{job_id}/attribution": { "get": { "description": "The attribution of a canary job's outcome.", "operationId": "operator.canaries.attribution", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanaryAttribution" } } }, "description": "read canary attribution" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "read canary attribution", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] } }, "/operator/api/dogfood/gate/evidence": { "post": { "description": "Verify gate evidence against the platform's own records and record it, attributed to the operator: a run record against the ledger and the job its submission key admitted, a credential against the dogfood tenant's credential inventory, a workflow run against GitHub Actions read through the App. An https reference is accepted, marked attested, only for the parts the platform cannot read. The seven-day clock starts when the recording opens the gate.", "operationId": "operator.dogfood.gate.record", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodGateEvidenceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodGateEvidenceRecorded" } } }, "description": "record gate evidence" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "record gate evidence", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "conflict" ] } }, "/operator/api/dogfood/incidents": { "post": { "description": "Record an incident an operator found, attributed to the operator: an outage the probe did not see, or a wrong green, cross-tenant disclosure, duplicate execution or duplicate charge naming the run records that exposed it, which stops the trial at once. The platform records unexpected outages and bounded recoveries itself.", "operationId": "operator.dogfood.incidents.record", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodIncidentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodIncident" } } }, "description": "record an incident" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "record an incident", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "conflict" ] } }, "/operator/api/dogfood/incidents/issue": { "post": { "description": "Record the issue filed for an incident in the dogfood repository. An issue filed on another UTC day than the incident is recorded and published as filed late.", "operationId": "operator.dogfood.incidents.issue", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodIncidentIssueRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodIncident" } } }, "description": "record an incident issue" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found", "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "record an incident issue", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "not_found", "invalid_request", "conflict" ] } }, "/operator/api/dogfood/incidents/resolution": { "post": { "description": "Resolve an incident, attributed to the operator. No run resolves an incident, and a trial stopped by one starts a new clock only once it is resolved.", "operationId": "operator.dogfood.incidents.resolve", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodIncidentResolutionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodIncident" } } }, "description": "resolve an incident" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found", "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "resolve an incident", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "not_found", "invalid_request", "conflict" ] } }, "/operator/api/dogfood/interventions": { "post": { "description": "Record an owner action taken during the period. A routine one is an action the platform was specified to take itself, and one routine intervention fails the period.", "operationId": "operator.dogfood.interventions.record", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodInterventionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodIntervention" } } }, "description": "record an owner intervention" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "record an owner intervention", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "conflict" ] } }, "/operator/api/dogfood/lifecycle-changes": { "post": { "description": "Record a material lifecycle change the probes cannot show, such as a host generation or reinstall that keeps the host's name. A window the change falls in does not count, and the consecutive count starts again after it.", "operationId": "operator.dogfood.lifecycle.record", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodLifecycleChangeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodLifecycleChange" } } }, "description": "record a lifecycle change" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "record a lifecycle change", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "conflict" ] } }, "/operator/api/dogfood/maintenance": { "post": { "description": "Declare an interval of at most 24 hours as maintenance before it begins. Every probe due inside it is accounted as declared maintenance, and a window containing it does not count.", "operationId": "operator.dogfood.maintenance.declare", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodMaintenanceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodMaintenance" } } }, "description": "declare maintenance" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "declare maintenance", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "conflict" ] } }, "/operator/api/dogfood/period": { "get": { "description": "The entry gate with each condition's parts and, for each, the evidence that meets it or what it lacks; the period's state, its clock and closed windows; every incident with its issue and resolution; the scorecard; and, once the period has ended, the beta decision record.", "operationId": "operator.dogfood.period", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodPeriod" } } }, "description": "read the dogfood period" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "read the dogfood period", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] } }, "/operator/api/dogfood/records": { "get": { "description": "A dogfood run record as published: every field, each absent one with its reason; the threshold labels it carries; and every incident that names it, with its issue and resolution.", "operationId": "operator.dogfood.records.get", "parameters": [ { "description": "the run record identity: shadow:, with # for a later attempt, probe:, or head:@ for a published head of the alpha workload", "in": "query", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodRunRecord" } } }, "description": "read a dogfood run record" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found", "not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "read a dogfood run record", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "not_found" ] } }, "/operator/api/dogfood/spend": { "post": { "description": "Record spend for one month from one provider or invoice. The scorecard compares the month's recorded spend with the ceiling of the recorded spend plan.", "operationId": "operator.dogfood.spend.record", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodSpendRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodSpend" } } }, "description": "record spend" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "record spend", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "conflict" ] } }, "/operator/api/hosts": { "get": { "description": "The host inventory with serving state, release and attribution.", "operationId": "operator.hosts.list", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostInventory" } } }, "description": "list hosts" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "list hosts", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] } }, "/operator/api/hosts/history": { "get": { "description": "Host lifecycle transitions.", "operationId": "operator.hosts.history", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostTransitions" } } }, "description": "list host transitions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "list host transitions", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] } }, "/operator/api/hosts/{id}": { "get": { "description": "One host's detail view.", "operationId": "operator.hosts.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostDetail" } } }, "description": "read a host" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "read a host", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] } }, "/operator/api/hosts/{id}/activations": { "get": { "description": "The host's in-place activations and promotions: admission and the host operator's closure, the host operation and its holder, the host operator's readiness as its last pass recorded it (its instance, when that instance started, the environment and host it reports for, the digest of the exact provisioning bundle it started on, whether it loaded the host's recovery binding and the installation that binding configures, and whether the bound provider identity is readable, never the identity itself), the boot that holds the host's authority, and each activation's plan and ledger with its receipt once it finished, the most recently written first. With operation, only that operation's. A host with no boot authority is not found. The read mutates nothing.", "operationId": "operator.hosts.activations.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "show only this activation's ledger; [a-z0-9][a-z0-9-]{0,62}", "in": "query", "name": "operation", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostActivations" } } }, "description": "read a host's activations" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found", "not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "read a host's activations", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "not_found" ] } }, "/operator/api/hosts/{id}/deployment": { "post": { "description": "Register a deployed release on a host.", "operationId": "operator.hosts.deployment.register", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostDeploymentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostInventoryView" } } }, "description": "register a host deployment" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "register a host deployment", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "conflict", "invalid_request" ] } }, "/operator/api/hosts/{id}/drain": { "post": { "description": "Stop placement on a host; running work continues.", "operationId": "operator.hosts.drain", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostInventoryView" } } }, "description": "drain a host" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "drain a host", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "conflict" ] } }, "/operator/api/hosts/{id}/evidence": { "get": { "description": "One host evidence file.", "operationId": "operator.hosts.evidence", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "the evidence file", "in": "query", "name": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "read a host evidence file; bytes" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "upstream_failed" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "read a host evidence file", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "upstream_failed" ] } }, "/operator/api/hosts/{id}/evidence-export": { "get": { "description": "One host boot's journal read consistently, the logs of its units and one named attempt's retained files, as JSON lines taken while the host keeps running; bounded, with every item it could not include named. Every read is attributed in the audit trail.", "operationId": "operator.hosts.evidence_export", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "the attempt whose retained files the snapshot carries", "in": "query", "name": "attempt", "required": false, "schema": { "type": "string" } }, { "description": "the most executions copied from the journal, newest first", "in": "query", "name": "executions", "required": false, "schema": { "type": "integer" } }, { "description": "the most bytes of records the snapshot holds", "in": "query", "name": "bytes", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "export a host evidence snapshot; bytes" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found", "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "upstream_failed" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "export a host evidence snapshot", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "not_found", "conflict", "upstream_failed" ] } }, "/operator/api/hosts/{id}/incidents/{incident}/approvals": { "post": { "description": "Record the operator's approval of one destructive step (reinstallation, partitioning or a filesystem operation) against the host's open incident. No destructive step is automatic; each waits for this approval, which names the host, the incident and the step.", "operationId": "operator.hosts.incidents.approve", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "incident", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestructiveStepApproval" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestructiveApproval" } } }, "description": "approve a destructive step" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found", "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "approve a destructive step", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "not_found", "conflict" ] } }, "/operator/api/hosts/{id}/incidents/{incident}/close": { "post": { "description": "Close the host's open incident as the operator's decision, at the incident revision the operator read. Admission is left as it stands, and a later impairment opens a new incident with its own automatic recovery.", "operationId": "operator.hosts.incidents.close", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "incident", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostIncidentClose" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostIncident" } } }, "description": "close a host incident" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found", "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "close a host incident", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "not_found", "conflict" ] } }, "/operator/api/hosts/{id}/initialization": { "get": { "description": "The recorded initialization state of a host.", "operationId": "operator.hosts.initialization.observe", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostInitialization" } } }, "description": "observe host initialization" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "observe host initialization", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] }, "post": { "description": "Start the audited first-boot initialization of a host.", "operationId": "operator.hosts.initialization.start", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostInitializationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostInitialization" } } }, "description": "start host initialization" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "upstream_failed" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "start host initialization", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "conflict", "invalid_request", "upstream_failed" ] } }, "/operator/api/hosts/{id}/journal": { "get": { "description": "A host's journal excerpt without shell access.", "operationId": "operator.hosts.journal", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "read a host journal; bytes" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "upstream_failed" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "read a host journal", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "upstream_failed" ] } }, "/operator/api/hosts/{id}/kernel-log": { "get": { "description": "A host's kernel log excerpt.", "operationId": "operator.hosts.kernel_log", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "read a host kernel log; bytes" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "upstream_failed" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "read a host kernel log", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "upstream_failed" ] } }, "/operator/api/hosts/{id}/recovery": { "get": { "description": "The host operator's recovery of a host: admission and the host operator's closure, the host operation and its holder, the per-host policy, the incident with the automatic recoveries it has spent and whether it awaits an operator, the newest recovery with its step ledger and who began it, and the recorded invocations. With operation, the recovery shown is that operation's rather than the newest, so an invocation is followed to its outcome by the operation it answered with. The read mutates nothing.", "operationId": "operator.hosts.recovery.get", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "show this operation's recovery and step ledger rather than the newest; [a-z0-9][a-z0-9-]{0,39}", "in": "query", "name": "operation", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostRecovery" } } }, "description": "read a host's recovery" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found", "not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "read a host's recovery", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "not_found" ] }, "post": { "description": "Record a recovery of the host for the host operator, which runs it; no step runs on the caller. The exact non-destructive confirmation is required. A second invocation while a recovery of the host is open or running returns that operation instead of starting another, and a retried invocation with the same request identifier replays the one it recorded. The surface and the operator are recorded with the operation.", "operationId": "operator.hosts.recovery.invoke", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostRecoveryInvocation" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostRecoveryInvocationOutcome" } } }, "description": "invoke a host recovery" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found", "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "invoke a host recovery", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "not_found", "conflict" ] } }, "/operator/api/hosts/{id}/recovery/policy": { "post": { "description": "Set whether the host operator takes automatic recovery for the host, at the policy revision the operator read. A host whose policy disables it still has admission closed and an incident opened on an impairment, and takes no further automatic action.", "operationId": "operator.hosts.recovery.policy.set", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostRecoveryPolicyUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostRecoveryPolicy" } } }, "description": "set a host's recovery policy" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found", "not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "set a host's recovery policy", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "not_found", "conflict" ] } }, "/operator/api/hosts/{id}/undrain": { "post": { "description": "Return a host to placement at a named policy revision.", "operationId": "operator.hosts.undrain", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UndrainRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostInventoryView" } } }, "description": "undrain a host" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "undrain a host", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "conflict", "invalid_request" ] } }, "/operator/api/identities": { "get": { "description": "Every host certificate, outstanding bootstrap credential, controller and provisioner identity with its issuer, window and remaining lifetime, or the named reason it has none, and each host's recovery key. Digests only.", "operationId": "operator.identities.list", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityInventory" } } }, "description": "list identities" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "list identities", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] } }, "/operator/api/placements": { "get": { "description": "Live placements, flagged first.", "operationId": "operator.placements.list", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Placements" } } }, "description": "list placements" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "list placements", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] } }, "/operator/api/placements/{job_id}/{vm_id}/receipt": { "get": { "description": "The finalized reap receipt of a placement, paged.", "operationId": "operator.placements.receipt", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "vm_id", "required": true, "schema": { "type": "string" } }, { "description": "the receipt page", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptRead" } } }, "description": "read a placement receipt" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "upstream_failed" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "read a placement receipt", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "upstream_failed" ] } }, "/operator/api/placements/{job_id}/{vm_id}/reconcile": { "post": { "description": "Reconcile one placement against its host now.", "operationId": "operator.placements.reconcile", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "vm_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileOutcome" } } }, "description": "reconcile a placement" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "upstream_failed" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "reconcile a placement", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "conflict", "upstream_failed" ] } }, "/operator/api/platform/states": { "get": { "description": "Management liveness, management readiness, execution capacity and end-to-end workload health, each with the instant it was computed, its typed reason and the deadline a refusing state is held to, and each host's reason for capacity.", "operationId": "operator.platform.states", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatingStates" } } }, "description": "read the operating states" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "read the operating states", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] } }, "/operator/api/tenants/{tenant}": { "get": { "description": "The operator-set controls of a tenant.", "operationId": "operator.tenants.controls.get", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantControls" } } }, "description": "read tenant controls" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "read tenant controls", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "safe", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] }, "post": { "description": "Set concurrency, storage, bandwidth, rate card or suspension for a tenant; platform staff only, audited.", "operationId": "operator.tenants.controls.set", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantControlUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantControls" } } }, "description": "set tenant controls" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "invalid_request" ] }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "conflict" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "set tenant controls", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable", "invalid_request", "conflict" ] } }, "/operator/auth/session": { "delete": { "description": "Close the operator session named by the cookie.", "operationId": "operator.session.delete", "parameters": [], "responses": { "204": { "description": "close an operator session" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_session": [] } ], "summary": "close an operator session", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] }, "post": { "description": "Present the operator bootstrap credential as a bearer token to open a session cookie; every other operator operation reads that cookie.", "operationId": "operator.session.create", "parameters": [], "responses": { "204": { "description": "open an operator session" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "operator_not_found" ] }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "description": "a typed refusal", "x-lathe-codes": [ "unavailable" ] } }, "security": [ { "operator_bootstrap": [] } ], "summary": "open an operator session", "tags": [ "operator" ], "x-lathe-cli": { "command": null, "reason": "operator operations are performed under the operator identity, not by tenant credentials" }, "x-lathe-idempotency": "unkeyed", "x-lathe-mcp-tool": null, "x-lathe-refusals": [ "operator_not_found", "unavailable" ] } } }, "servers": [ { "url": "https://app.lathe.run" } ], "tags": [ { "name": "sources" }, { "name": "openapi" }, { "name": "device" }, { "name": "identity" }, { "name": "onboarding" }, { "name": "jobs" }, { "name": "repositories" }, { "name": "tenant" }, { "name": "cli_tokens" }, { "name": "cli" }, { "name": "events" }, { "name": "usage" }, { "name": "credentials" }, { "name": "audit" }, { "name": "operator" } ], "x-lathe-refusals": [ { "code": "unauthenticated", "meaning": "no credential or session was presented, or it did not verify", "status": 401 }, { "code": "credential_revoked", "meaning": "the presented credential was revoked; the refusal names the revocation", "status": 401 }, { "code": "credential_expired", "meaning": "the presented credential passed its expiry; the refusal names the expiry", "status": 401 }, { "code": "out_of_scope", "meaning": "the credential does not hold the operation's scope; the refusal names the scope", "status": 403 }, { "code": "role_required", "meaning": "the session's role does not permit the operation; the refusal names the role", "status": 403 }, { "code": "human_principal_required", "meaning": "the operation is a human act; no agent credential performs it", "status": 403 }, { "code": "session_required", "meaning": "the operation is performed only inside a signed-in session", "status": 403 }, { "code": "operator_controlled", "meaning": "the setting changes only through the operator console", "status": 403 }, { "code": "not_found", "meaning": "the record does not exist for the active tenant", "status": 404 }, { "code": "gone", "meaning": "the record's retention expired; it is no longer served and retention is not extended", "status": 410 }, { "code": "invalid_request", "meaning": "the request did not satisfy the operation's schema or rules; the detail names the field", "status": 400 }, { "code": "idempotency_key_required", "meaning": "the mutation carried no idempotency-key header or more than one", "status": 400 }, { "code": "idempotency_key_reused", "meaning": "the idempotency-key was used with a different request body inside the retention window", "status": 409 }, { "code": "idempotency_key_in_flight", "meaning": "the idempotency-key's first request is still being performed; a repeat after it answers receives its receipt", "status": 409 }, { "code": "stale_version", "meaning": "the settings write named a version the record has moved past; the refusal names the current version", "status": 409 }, { "code": "conflict", "meaning": "the record's state does not admit the mutation; the detail names the state", "status": 409 }, { "code": "confirmation_required", "meaning": "the mutation did not carry the confirmation its consequence requires", "status": 400 }, { "code": "rate_limited", "meaning": "the credential's request limit was reached; the refusal names the reset time", "status": 429 }, { "code": "unavailable", "meaning": "a store or service the operation needs did not answer; retry after the named interval", "status": 503 }, { "code": "legacy_unsupported", "meaning": "the composed runtime does not serve the retained predecessor form", "status": 501 }, { "code": "upstream_failed", "meaning": "a provider the operation depends on refused or failed", "status": 502 }, { "code": "operator_not_found", "meaning": "the operator surface answers not found to every caller without an operator session", "status": 404 } ], "x-lathe-scopes": [ { "role": "viewer", "scope": "read" }, { "role": "member", "scope": "submit" }, { "role": "admin", "scope": "settings" }, { "role": "admin", "scope": "credentials" }, { "role": "admin", "scope": "admin" } ] }