api reference

Source snapshot, not a live availability guarantee. Use the client and release supplied during onboarding. Contributor build instructions below refer to the source workspace; they are not a public package installer. Version notes.

Generated from the operation catalogue; the served document is https://app.lathe.run/api/openapi.json. Every operation below is an operation of that document, with the same identifier.

authentication

• Tenant credential: Authorization: Bearer <credential>. A CLI device token (lathe_cli_...) carries the person’s role; an agent credential (lathe_agent_...) carries its scopes.
• Scopes: read (viewer), submit (member), settings, credentials and admin (admin or owner). A person’s role maps onto scopes as bracketed.
• Dashboard session: the lathe_session cookie, for the browser. Over HTTP it reaches the session-only operations, which perform human acts, and the operations the browser reads directly (jobs.logs, jobs.logs_stream, usage.export); every other operation the dashboard performs in-process as the signed-in person, and requires a bearer credential over HTTP.
• Operator session: the lathe_operator_session cookie under the operator identity; every tenant credential is answered not found.

contract

• Every customer mutation requires one idempotency-key header. General mutations retain their receipt for 24 hours, refuse a changed body as idempotency_key_reused, and report idempotency_key_in_flight while their five-minute reservation remains outstanding. Job submission and source transfer instead reconcile their durable original owner: equal retries preserve the original job or upload, and changed input conflicts. Source mutation keys are the upload ID, containing 1 to 128 ASCII letters, digits, -, _, ., or :. Chunk keys are additionally bound to their path’s part number.
• The source archive protocol separates a 1 GiB regular-file budget, 250000 file/link entries, 250000 derived directories and 32 MiB metadata from its 4 MiB raw transfer chunks. The verified identity binds directory demand for scratch accounting. Uploads expire after one hour; expired bytes still count toward the tenant’s 16 GiB and 32-unclaimed-upload reservations until cleanup completes. Runtime availability and execution support require separately qualified management, host, guest and CLI composition.
• Settings writes carry the version the caller observed; a moved version is refused as stale_version naming the current one.
• Every list pages by an opaque cursor in a stable order and returns next_cursor while rows remain; limit is 1 to 1000, 200 by default.
• Every refusal is a JSON Refusal document: code, status, detail and the members the code names.
• Every job, settings write, credential operation, audit entry and usage record names its principal: the user id for a person, agent:<name> for an agent.

refusal codes

code	status	meaning
unauthenticated	401	no credential or session was presented, or it did not verify
credential_revoked	401	the presented credential was revoked; the refusal names the revocation
credential_expired	401	the presented credential passed its expiry; the refusal names the expiry
out_of_scope	403	the credential does not hold the operation’s scope; the refusal names the scope
role_required	403	the session’s role does not permit the operation; the refusal names the role
human_principal_required	403	the operation is a human act; no agent credential performs it
session_required	403	the operation is performed only inside a signed-in session
operator_controlled	403	the setting changes only through the operator console
not_found	404	the record does not exist for the active tenant
gone	410	the record’s retention expired; it is no longer served and retention is not extended
invalid_request	400	the request did not satisfy the operation’s schema or rules; the detail names the field
idempotency_key_required	400	the mutation carried no idempotency-key header or more than one
idempotency_key_reused	409	the idempotency-key was used with a different request body inside the retention window
idempotency_key_in_flight	409	the idempotency-key’s first request is still being performed; a repeat after it answers receives its receipt
stale_version	409	the settings write named a version the record has moved past; the refusal names the current version
conflict	409	the record’s state does not admit the mutation; the detail names the state
confirmation_required	400	the mutation did not carry the confirmation its consequence requires
rate_limited	429	the credential’s request limit was reached; the refusal names the reset time
unavailable	503	a store or service the operation needs did not answer; retry after the named interval
legacy_unsupported	501	the composed runtime does not serve the retained predecessor form
upstream_failed	502	a provider the operation depends on refused or failed
operator_not_found	404	the operator surface answers not found to every caller without an operator session

sources

sources.capabilities

GET /api/source-capabilities — read source transport capabilities

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.

• security: tenant credential with the submit scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least member
• idempotency: safe read
• query repository (required): the authorized repository owning this upload
• response: SourceCapabilities (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, invalid_request, not_found
• cli: cargo sorus test

sources.reserve

POST /api/sources — reserve captured source

Reserve immutable source identity for an onboarded repository. The idempotency-key is the upload ID and remains bound to these exact inputs.

• security: tenant credential with the submit scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least member
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• body: SourceReservation (application/json)
• response: SourceUpload (application/json)
• 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
• cli: cargo sorus test

sources.status

GET /api/sources/{upload} — read source upload status

Read the original tenant and repository bound upload, including expiry and retained admission state.

• security: tenant credential with the submit scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least member
• idempotency: safe read
• path: upload
• query repository (required): the authorized repository owning this upload
• response: SourceUpload (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, invalid_request, not_found
• cli: cargo sorus test

sources.chunk.put

POST /api/sources/{upload}/chunks/{part} — upload an immutable source chunk

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.

• security: tenant credential with the submit scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least member
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• path: upload, part
• query repository (required): the authorized repository owning this upload
• body: SourceChunk (application/octet-stream)
• response: no body
• 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
• cli: cargo sorus test

sources.chunk.check

GET /api/sources/{upload}/chunks/{part} — verify a retained source chunk

Verify a retained chunk against the caller’s SHA-256 before resuming. An absent chunk reports present=false; changed bytes conflict.

• security: tenant credential with the submit scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least member
• idempotency: safe read
• path: upload, part
• query repository (required): the authorized repository owning this upload
• query sha256 (required): 64 lowercase hexadecimal SHA-256 digits
• response: SourceChunkStatus (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, invalid_request, not_found, gone, conflict
• cli: cargo sorus test

sources.complete

POST /api/sources/{upload}/complete — verify completed source

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.

• security: tenant credential with the submit scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least member
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• path: upload
• query repository (required): the authorized repository owning this upload
• response: SourceUpload (application/json)
• 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
• cli: cargo sorus test

openapi

openapi.document

GET /api/openapi.json — the served OpenAPI document

The document this build serves, generated from the catalogue that also binds the routes.

• security: public; no credential
• idempotency: safe read
• response: OpenApiDocument (application/json)
• refusals: unavailable
• cli: cargo sorus openapi (generated)

device

device.start

POST /api/device/start — start a device authorization

Begin the CLI device flow. The answer names the approval page and the user code a signed-in person confirms there.

• security: public; no credential
• idempotency: operator mutation; audited, not keyed
• response: DeviceAuthorization (application/json)
• refusals: rate_limited, upstream_failed, unavailable
• cli: cargo sorus login

device.poll

GET /api/device/poll — poll a device authorization

Poll the device flow until a person approves the code; an approved poll issues the device token once.

• security: public; no credential
• idempotency: safe read
• query device_code (required): the device code the start answered with
• response: DevicePoll (application/json)
• refusals: rate_limited, unavailable
• cli: cargo sorus login

device.pending

GET /api/device/pending — read a pending device code

The pending device authorization for a user code, for the approval page inside a signed-in session.

• security: signed-in dashboard session only; no credential of any scope
• idempotency: safe read
• query user_code (required): the user code the CLI printed
• response: PendingDevice (application/json)
• refusals: unauthenticated, session_required, unavailable
• cli: none: the approval page is a human surface inside a signed-in session

device.approve

POST /api/device/approve — approve a device code

Approve a pending device code. Only a signed-in human session performs this; no credential, scope or other operation approves a device code.

• security: signed-in dashboard session only; no credential of any scope
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• query user_code (required): the user code to approve
• response: DeviceApprovalReceipt (application/json)
• refusals: unauthenticated, session_required, invalid_request, idempotency_key_required, idempotency_key_reused, idempotency_key_in_flight
• cli: none: device approval is a human act inside a signed-in session

identity

identity.current

GET /api/identity — the calling principal

The principal the credential or session resolves to: a person with role and memberships, or an agent with its scopes.

• security: tenant credential with the read scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least viewer
• idempotency: safe read
• response: Identity (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable
• cli: cargo sorus whoami (generated)
• mcp tool: identity_current

onboarding

onboarding.surface

GET /api/onboarding — the onboarding state

Whether the GitHub App installation is claimed, the installation and claim links, and whether a job has arrived.

• security: tenant credential with the read scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least viewer
• idempotency: safe read
• response: Onboarding (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable
• cli: cargo sorus onboarding status (generated)
• mcp tool: onboarding_surface

onboarding.claim

POST /api/onboarding/claims — claim a GitHub App installation

Link an installation to the active tenant. Requires the admin scope; the claim is attributed to the caller.

• security: tenant credential with the admin scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least admin
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• body: ClaimRequest (application/json)
• response: ClaimReceipt (application/json)
• 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
• cli: cargo sorus onboarding claim (generated)
• mcp tool: onboarding_claim

jobs

jobs.list

GET /api/jobs — list jobs

Jobs of the active tenant, newest first, filtered and paged by an opaque cursor in a stable order.

• security: tenant credential with the read scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least viewer
• idempotency: safe read
• query repository: only jobs of this owner/name repository
• query branch: only jobs of this branch
• query status: only jobs in this status
• query class: only jobs of this class
• query cursor: the opaque cursor a previous page returned; absent starts at the newest row
• query limit: rows per page, 1 to 1000; the default is 200
• response: JobsPage (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, invalid_request
• cli: cargo sorus jobs list (generated)
• mcp tool: jobs_list

jobs.submit

POST /api/v4/jobs — submit a captured Cargo workspace

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.

• security: tenant credential with the submit scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least member
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• body: CargoWorkspaceRequest (application/json)
• response: JobId (application/json)
• 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
• cli: cargo sorus test
• mcp tool: jobs_submit

jobs.get

GET /api/jobs/{id} — read a job

The authoritative job record.

• security: tenant credential with the read scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least viewer
• idempotency: safe read
• path: id
• response: Job (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, not_found
• cli: cargo sorus jobs get (generated)
• mcp tool: jobs_get

jobs.evidence

GET /api/jobs/{id}/evidence — read a job’s evidence

The job, its evidence report, its usage record and, paged by cursor, its attempt evidence.

• security: tenant credential with the read scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least viewer
• idempotency: safe read
• path: id
• query cursor: the attempt evidence cursor a previous page returned
• response: JobEvidence (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, not_found, invalid_request
• cli: cargo sorus jobs evidence (generated)
• mcp tool: jobs_evidence

jobs.cargo_output

GET /api/jobs/{id}/attempts/{attempt}/cargo-output — download an attempt’s Cargo output

The retained Cargo output of one attempt as bytes.

• security: tenant credential with the read scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least viewer
• idempotency: safe read
• path: id, attempt
• response: bytes
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, not_found
• cli: cargo sorus logs

jobs.artifacts

GET /api/jobs/{id}/artifacts — list a job’s artifacts

The published artifact inventory of a job.

• security: tenant credential with the read scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least viewer
• idempotency: safe read
• path: id
• response: ArtifactInventory (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, not_found, gone
• cli: cargo sorus artifacts
• mcp tool: jobs_artifacts

jobs.artifact_bytes

GET /api/jobs/{id}/artifacts/{attempt}/{index} — download an artifact

One published artifact file as bytes.

• security: tenant credential with the read scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least viewer
• idempotency: safe read
• path: id, attempt, index
• response: bytes
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, not_found, gone
• cli: cargo sorus artifacts

jobs.logs

GET /api/jobs/{id}/logs — read a page of job logs

One page of durable job log records from a cursor.

• security: tenant credential with the read scope as a bearer token; the signed-in dashboard session reaches it with its cookie at a role of at least viewer
• idempotency: safe read
• path: id
• query cursor: the log cursor a previous page returned
• query limit: records per page; the default is 100
• response: JobLogPage (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, not_found, invalid_request
• cli: cargo sorus logs
• mcp tool: jobs_logs

jobs.logs_stream

GET /api/jobs/{id}/logs/stream — stream job logs

Job log pages as server-sent events from a cursor until the job settles.

• security: tenant credential with the read scope as a bearer token; the signed-in dashboard session reaches it with its cookie at a role of at least viewer
• idempotency: safe read
• path: id
• query cursor: the log cursor to resume from
• query limit: records per page
• response: server-sent events
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, not_found, invalid_request
• cli: cargo sorus logs

jobs.cancel

POST /api/jobs/{id}/cancel — cancel a job

Request cancellation; running units are reaped and metering closes.

• security: tenant credential with the submit scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least member
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• path: id
• response: CancellationReceipt (application/json)
• 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
• cli: cargo sorus cancel
• mcp tool: jobs_cancel

jobs.retry

POST /api/jobs/{id}/retry — retry a terminal job

Submit a fresh job linked to a terminal original.

• security: tenant credential with the submit scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least member
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• path: id
• response: RetryReceipt (application/json)
• 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
• cli: cargo sorus jobs retry (generated)
• mcp tool: jobs_retry

repositories

repositories.admission

GET /api/repositories/{owner}/{name}/admission — resolve a repository’s merge base

Confirm the repository is onboarded and resolve the merge base of a base ref before a local submission.

• security: tenant credential with the submit scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least member
• idempotency: safe read
• path: owner, name
• query base_ref (required): the base ref to resolve
• response: Admission (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, not_found, upstream_failed
• cli: cargo sorus repositories admission (generated)
• mcp tool: repositories_admission

repositories.list

GET /api/repositories — list repositories

Onboarded repositories with their lineage storage, the tenant quota and live advisories, paged by cursor.

• security: tenant credential with the read scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least viewer
• idempotency: safe read
• query cursor: the opaque cursor a previous page returned; absent starts at the newest row
• query limit: rows per page, 1 to 1000; the default is 200
• response: RepositoriesPage (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, invalid_request
• cli: cargo sorus repositories list (generated)
• mcp tool: repositories_list

repositories.get

GET /api/repositories/{owner}/{name} — read a repository

One repository: its lineages by class against the quota and its advisories with their measured basis.

• security: tenant credential with the read scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least viewer
• idempotency: safe read
• path: owner, name
• response: RepositoryPage (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, not_found
• cli: cargo sorus repositories get (generated)
• mcp tool: repositories_get

repositories.settings.get

GET /api/repositories/{owner}/{name}/settings — read repository settings

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.

• security: tenant credential with the submit scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least member
• idempotency: safe read
• path: owner, name
• response: RepositorySettings (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, not_found
• cli: cargo sorus repositories settings get (generated)
• mcp tool: repositories_settings_get

repositories.settings.write

POST /api/repositories/{owner}/{name}/settings — write a repository setting

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.

• security: tenant credential with the settings scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least admin
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• path: owner, name
• body: SettingWrite (application/json)
• response: SettingReceipt (application/json)
• 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
• cli: cargo sorus repositories settings set (generated)
• mcp tool: repositories_settings_write

repositories.advisories.dismiss

POST /api/repositories/{owner}/{name}/advisories/{advisory}/dismissal — dismiss an advisory

Dismiss a repository advisory; the dismissal is remembered and attributed.

• security: tenant credential with the settings scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least admin
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• path: owner, name, advisory
• response: DismissalReceipt (application/json)
• 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
• cli: cargo sorus repositories advisories dismiss (generated)
• mcp tool: repositories_advisories_dismiss

repositories.lineages.purge

POST /api/repositories/{owner}/{name}/purges — purge a lineage

Delete a lineage so the next matching job starts cold. The request carries the confirmation the consequence requires.

• security: tenant credential with the admin scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least admin
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• path: owner, name
• body: PurgeRequest (application/json)
• response: PurgeReceipt (application/json)
• 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
• cli: cargo sorus repositories lineages purge (generated)
• mcp tool: repositories_lineages_purge

tenant

tenant.settings.get

GET /api/tenant/settings — read tenant settings

The tenant policy with its version and attribution, and the operator-set limits beside current consumption.

• security: tenant credential with the read scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least viewer
• idempotency: safe read
• response: TenantSettings (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable
• cli: cargo sorus settings get (generated)
• mcp tool: tenant_settings_get

tenant.settings.write

POST /api/tenant/settings — write a tenant setting

Write one tenant-editable setting at the version the caller observed. Operator-controlled settings are refused and the refusal is audited.

• security: tenant credential with the settings scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least admin
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• body: SettingWrite (application/json)
• response: SettingReceipt (application/json)
• 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
• cli: cargo sorus settings set (generated)
• mcp tool: tenant_settings_write

tenant.registry_credential.replace

POST /api/tenant/registry-credentials — replace a private registry credential

Replace a registry credential on every host, removing the prior value once every host acknowledges. The request carries the confirmation.

• security: tenant credential with the credentials scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least admin
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• body: RegistryCredentialReplacement (application/json)
• response: RegistryCredentialReceipt (application/json)
• 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
• cli: cargo sorus registry-credential replace (generated)
• mcp tool: tenant_registry_credential_replace

cli_tokens

cli_tokens.list

GET /api/cli/tokens — list the caller’s CLI tokens

The calling person’s device tokens with creation, last use and revocation, paged by cursor. Tokens belong to people; an agent credential is refused.

• security: a person’s device token with the credentials scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least admin; an agent credential is refused
• idempotency: safe read
• query cursor: the opaque cursor a previous page returned; absent starts at the newest row
• query limit: rows per page, 1 to 1000; the default is 200
• response: TokensPage (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, human_principal_required, invalid_request
• cli: cargo sorus tokens list (generated)

cli_tokens.revoke

POST /api/cli/tokens/{id}/revocation — revoke a CLI token

Revoke one of the caller’s device tokens; the next request presenting it is refused.

• security: a person’s device token with the credentials scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least admin; an agent credential is refused
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• path: id
• response: RevocationReceipt (application/json)
• 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
• cli: cargo sorus tokens revoke (generated)

cli

cli.tenant

GET /api/cli/tenant — the credential’s tenant

The tenant the credential is bound to.

• security: tenant credential with the read scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least viewer
• idempotency: safe read
• response: TenantId (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable
• cli: cargo sorus tenant (generated)
• mcp tool: cli_tenant

cli.events

GET /api/cli/events — stream tenant job events

Tenant job status events as server-sent events, resumable from a durable sequence.

• security: tenant credential with the read scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least viewer
• idempotency: safe read
• query after: the durable sequence already observed
• response: server-sent events
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, invalid_request
• cli: cargo sorus status

events

events.stream

GET /api/events — stream dashboard hints

Job transitions for the signed-in session’s tenant as server-sent events; hints the dashboard reconciles against authoritative reads.

• security: signed-in dashboard session only; no credential of any scope
• idempotency: safe read
• response: server-sent events
• refusals: unauthenticated, session_required, rate_limited
• cli: none: the dashboard hint stream is a browser session surface; the CLI reads the tenant event stream

usage

usage.report

GET /api/usage — read the usage report

The period’s usage rolled up from per-second records, per day and per repository, with the rate card where one is set.

• security: tenant credential with the read scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least viewer
• idempotency: safe read
• query period: the period as YYYY-MM; absent means the current month
• response: Usage (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, invalid_request
• cli: cargo sorus usage report (generated)
• mcp tool: usage_report

usage.export

GET /api/usage/export — export the period’s records

The period’s per-second records and adjustments as a document whose totals equal the report.

• security: tenant credential with the read scope as a bearer token; the signed-in dashboard session reaches it with its cookie at a role of at least viewer
• idempotency: safe read
• query period: the period as YYYY-MM; absent means the current month
• response: UsageExport (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, invalid_request
• cli: cargo sorus usage export (generated)
• mcp tool: usage_export

credentials

credentials.create

POST /api/credentials — mint an agent credential

Mint a named, scoped, expiring agent credential. The value is shown once. A human admin performs this; no agent credential mints another.

• security: a person’s device token with the admin scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least admin; an agent credential is refused
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• body: CredentialRequest (application/json)
• response: CredentialIssued (application/json)
• 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
• cli: cargo sorus credential create

credentials.list

GET /api/credentials — list agent credentials

The tenant’s agent credentials with name, scopes, expiry, last use and revocation, paged by cursor.

• security: tenant credential with the credentials scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least admin
• idempotency: safe read
• query cursor: the opaque cursor a previous page returned; absent starts at the newest row
• query limit: rows per page, 1 to 1000; the default is 200
• response: CredentialsPage (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, invalid_request
• cli: cargo sorus credential list (generated)
• mcp tool: credentials_list

credentials.revoke

POST /api/credentials/{name}/revocation — revoke an agent credential

Revoke a credential by name; its next use is refused as revoked.

• security: tenant credential with the credentials scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least admin
• idempotency: keyed mutation: idempotency-key required; a replay with the same key and body answers the original receipt
• path: name
• response: CredentialRevocationReceipt (application/json)
• 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
• cli: cargo sorus credential revoke (generated)
• mcp tool: credentials_revoke

audit

audit.list

GET /api/audit — list tenant audit entries

Attributed management mutations of the tenant, newest first, paged by cursor.

• security: tenant credential with the read scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least viewer
• idempotency: safe read
• query cursor: the opaque cursor a previous page returned; absent starts at the newest row
• query limit: rows per page, 1 to 1000; the default is 200
• response: AuditPage (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, invalid_request
• cli: cargo sorus audit list (generated)
• mcp tool: audit_list

jobs

jobs.submit_diff

POST /api/jobs — submit a local diff (predecessor) (deprecated)

A retained predecessor route. The attempt runtime refuses it and names the captured Cargo workspace submission; new clients do not call it.

• security: tenant credential with the submit scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least member
• idempotency: predecessor mutation; not keyed
• body: LocalDiffRequest (application/json)
• response: JobId (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, invalid_request, not_found, conflict, legacy_unsupported, idempotency_key_required
• cli: none: a retained predecessor route; the CLI submits captured Cargo workspaces

jobs.submit_diff_v2

POST /api/v2/jobs — submit a local diff with artifacts (predecessor) (deprecated)

A retained predecessor route. The attempt runtime refuses it and names the captured Cargo workspace submission; new clients do not call it.

• security: tenant credential with the submit scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least member
• idempotency: predecessor mutation; not keyed
• body: LocalDiffRequest (application/json)
• response: JobId (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, invalid_request, not_found, conflict, legacy_unsupported, idempotency_key_required
• cli: none: a retained predecessor route; the CLI submits captured Cargo workspaces

jobs.submit_diff_keyed

POST /api/v3/jobs — submit a local diff with an idempotency-key (predecessor) (deprecated)

A retained predecessor route. The attempt runtime refuses it and names the captured Cargo workspace submission; new clients do not call it.

• security: tenant credential with the submit scope as a bearer token; the dashboard reaches it in-process with its session at a role of at least member
• idempotency: predecessor mutation; not keyed
• body: LocalDiffRequest (application/json)
• response: JobId (application/json)
• refusals: unauthenticated, credential_revoked, credential_expired, out_of_scope, role_required, rate_limited, unavailable, invalid_request, not_found, conflict, legacy_unsupported, idempotency_key_required
• cli: none: a retained predecessor route; the CLI submits captured Cargo workspaces

operator

operator.session.create

POST /operator/auth/session — open an operator session

Present the operator bootstrap credential as a bearer token to open a session cookie; every other operator operation reads that cookie.

• security: the operator bootstrap credential as a bearer token
• idempotency: operator mutation; audited, not keyed
• response: no body
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.session.delete

DELETE /operator/auth/session — close an operator session

Close the operator session named by the cookie.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• response: no body
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.tenants.controls.get

GET /operator/api/tenants/{tenant} — read tenant controls

The operator-set controls of a tenant.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• path: tenant
• response: TenantControls (application/json)
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.tenants.controls.set

POST /operator/api/tenants/{tenant} — set tenant controls

Set concurrency, storage, bandwidth, rate card or suspension for a tenant; platform staff only, audited.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• path: tenant
• body: TenantControlUpdate (application/json)
• response: TenantControls (application/json)
• refusals: operator_not_found, unavailable, invalid_request, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.anomalies.list

GET /operator/api/anomalies — list anomaly flags

Queued usage anomaly flags with their evidence.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• response: OperatorAnomalies (application/json)
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.anomalies.disposition

POST /operator/api/anomalies/{id}/disposition — record a flag disposition

Record the disposition of an anomaly flag, attributed to the operator.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• path: id
• body: FlagDispositionRequest (application/json)
• response: OperatorAnomaly (application/json)
• refusals: operator_not_found, unavailable, invalid_request
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.anomalies.platform.list

GET /operator/api/anomalies/platform — list platform anomalies

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.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• response: PlatformAnomalies (application/json)
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.anomalies.platform.disposition

POST /operator/api/anomalies/platform/{id}/disposition — record a platform anomaly disposition

Record the disposition of a platform anomaly, attributed to the operator. It changes no job, attempt, host or admission.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• path: id
• body: PlatformAnomalyDispositionRequest (application/json)
• response: PlatformAnomaly (application/json)
• refusals: operator_not_found, unavailable, invalid_request
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.platform.states

GET /operator/api/platform/states — read the operating states

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.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• response: OperatingStates (application/json)
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.dogfood.period

GET /operator/api/dogfood/period — read the dogfood period

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.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• response: DogfoodPeriod (application/json)
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.dogfood.records.get

GET /operator/api/dogfood/records — read a dogfood run record

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.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• query id (required): the run record identity: shadow:, with # for a later attempt, probe:, or head:<owner/name>@ for a published head of the alpha workload
• response: DogfoodRunRecord (application/json)
• refusals: operator_not_found, unavailable, invalid_request, not_found
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.dogfood.gate.record

POST /operator/api/dogfood/gate/evidence — record gate evidence

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.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• body: DogfoodGateEvidenceRequest (application/json)
• response: DogfoodGateEvidenceRecorded (application/json)
• refusals: operator_not_found, unavailable, invalid_request, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.dogfood.incidents.record

POST /operator/api/dogfood/incidents — record an incident

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.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• body: DogfoodIncidentRequest (application/json)
• response: DogfoodIncident (application/json)
• refusals: operator_not_found, unavailable, invalid_request, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.dogfood.incidents.issue

POST /operator/api/dogfood/incidents/issue — record an incident issue

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.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• body: DogfoodIncidentIssueRequest (application/json)
• response: DogfoodIncident (application/json)
• refusals: operator_not_found, unavailable, not_found, invalid_request, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.dogfood.incidents.resolve

POST /operator/api/dogfood/incidents/resolution — resolve an incident

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.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• body: DogfoodIncidentResolutionRequest (application/json)
• response: DogfoodIncident (application/json)
• refusals: operator_not_found, unavailable, not_found, invalid_request, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.dogfood.maintenance.declare

POST /operator/api/dogfood/maintenance — declare maintenance

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.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• body: DogfoodMaintenanceRequest (application/json)
• response: DogfoodMaintenance (application/json)
• refusals: operator_not_found, unavailable, invalid_request, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.dogfood.interventions.record

POST /operator/api/dogfood/interventions — record an owner intervention

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.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• body: DogfoodInterventionRequest (application/json)
• response: DogfoodIntervention (application/json)
• refusals: operator_not_found, unavailable, invalid_request, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.dogfood.lifecycle.record

POST /operator/api/dogfood/lifecycle-changes — record a lifecycle change

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.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• body: DogfoodLifecycleChangeRequest (application/json)
• response: DogfoodLifecycleChange (application/json)
• refusals: operator_not_found, unavailable, invalid_request, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.dogfood.spend.record

POST /operator/api/dogfood/spend — record spend

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.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• body: DogfoodSpendRequest (application/json)
• response: DogfoodSpend (application/json)
• refusals: operator_not_found, unavailable, invalid_request, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.list

GET /operator/api/hosts — list hosts

The host inventory with serving state, release and attribution.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• response: HostInventory (application/json)
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.identities.list

GET /operator/api/identities — list identities

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.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• response: IdentityInventory (application/json)
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.history

GET /operator/api/hosts/history — list host transitions

Host lifecycle transitions.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• response: HostTransitions (application/json)
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.get

GET /operator/api/hosts/{id} — read a host

One host’s detail view.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• path: id
• response: HostDetail (application/json)
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.placements.list

GET /operator/api/placements — list placements

Live placements, flagged first.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• response: Placements (application/json)
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.placements.reconcile

POST /operator/api/placements/{job_id}/{vm_id}/reconcile — reconcile a placement

Reconcile one placement against its host now.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• path: job_id, vm_id
• body: ReconcileRequest (application/json)
• response: ReconcileOutcome (application/json)
• refusals: operator_not_found, unavailable, invalid_request, conflict, upstream_failed
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.placements.receipt

GET /operator/api/placements/{job_id}/{vm_id}/receipt — read a placement receipt

The finalized reap receipt of a placement, paged.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• path: job_id, vm_id
• query page: the receipt page
• response: ReceiptRead (application/json)
• refusals: operator_not_found, unavailable, upstream_failed
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.canaries.attribution

GET /operator/api/canaries/{job_id}/attribution — read canary attribution

The attribution of a canary job’s outcome.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• path: job_id
• response: CanaryAttribution (application/json)
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.journal

GET /operator/api/hosts/{id}/journal — read a host journal

A host’s journal excerpt without shell access.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• path: id
• response: bytes
• refusals: operator_not_found, unavailable, upstream_failed
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.kernel_log

GET /operator/api/hosts/{id}/kernel-log — read a host kernel log

A host’s kernel log excerpt.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• path: id
• response: bytes
• refusals: operator_not_found, unavailable, upstream_failed
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.evidence

GET /operator/api/hosts/{id}/evidence — read a host evidence file

One host evidence file.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• path: id
• query path (required): the evidence file
• response: bytes
• refusals: operator_not_found, unavailable, upstream_failed
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.evidence_export

GET /operator/api/hosts/{id}/evidence-export — export a host evidence snapshot

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.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• path: id
• query attempt: the attempt whose retained files the snapshot carries
• query executions: the most executions copied from the journal, newest first
• query bytes: the most bytes of records the snapshot holds
• response: bytes
• refusals: operator_not_found, unavailable, invalid_request, not_found, conflict, upstream_failed
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.drain

POST /operator/api/hosts/{id}/drain — drain a host

Stop placement on a host; running work continues.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• path: id
• response: HostInventoryView (application/json)
• refusals: operator_not_found, unavailable, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.undrain

POST /operator/api/hosts/{id}/undrain — undrain a host

Return a host to placement at a named policy revision.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• path: id
• body: UndrainRequest (application/json)
• response: HostInventoryView (application/json)
• refusals: operator_not_found, unavailable, conflict, invalid_request
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.initialization.start

POST /operator/api/hosts/{id}/initialization — start host initialization

Start the audited first-boot initialization of a host.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• path: id
• body: HostInitializationRequest (application/json)
• response: HostInitialization (application/json)
• refusals: operator_not_found, unavailable, conflict, invalid_request, upstream_failed
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.initialization.observe

GET /operator/api/hosts/{id}/initialization — observe host initialization

The recorded initialization state of a host.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• path: id
• response: HostInitialization (application/json)
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.deployment.register

POST /operator/api/hosts/{id}/deployment — register a host deployment

Register a deployed release on a host.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• path: id
• body: HostDeploymentRequest (application/json)
• response: HostInventoryView (application/json)
• refusals: operator_not_found, unavailable, conflict, invalid_request
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.recovery.get

GET /operator/api/hosts/{id}/recovery — read a host’s recovery

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.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• path: id
• query operation: show this operation’s recovery and step ledger rather than the newest; [a-z0-9][a-z0-9-]{0,39}
• response: HostRecovery (application/json)
• refusals: operator_not_found, unavailable, invalid_request, not_found
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.activations.get

GET /operator/api/hosts/{id}/activations — read a host’s activations

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.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• path: id
• query operation: show only this activation’s ledger; [a-z0-9][a-z0-9-]{0,62}
• response: HostActivations (application/json)
• refusals: operator_not_found, unavailable, invalid_request, not_found
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.recovery.invoke

POST /operator/api/hosts/{id}/recovery — invoke a host recovery

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.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• path: id
• body: HostRecoveryInvocation (application/json)
• response: HostRecoveryInvocationOutcome (application/json)
• refusals: operator_not_found, unavailable, invalid_request, not_found, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.recovery.policy.set

POST /operator/api/hosts/{id}/recovery/policy — set a host’s recovery policy

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.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• path: id
• body: HostRecoveryPolicyUpdate (application/json)
• response: HostRecoveryPolicy (application/json)
• refusals: operator_not_found, unavailable, invalid_request, not_found, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.incidents.approve

POST /operator/api/hosts/{id}/incidents/{incident}/approvals — approve a destructive step

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.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• path: id, incident
• body: DestructiveStepApproval (application/json)
• response: DestructiveApproval (application/json)
• refusals: operator_not_found, unavailable, invalid_request, not_found, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.hosts.incidents.close

POST /operator/api/hosts/{id}/incidents/{incident}/close — close a host incident

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.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• path: id, incident
• body: HostIncidentClose (application/json)
• response: HostIncident (application/json)
• refusals: operator_not_found, unavailable, invalid_request, not_found, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.audit.list

GET /operator/api/audit — list the operator audit

The operator audit trail.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• response: OperatorAudit (application/json)
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.audit.export

GET /operator/api/audit/export — export the operator audit

The operator audit trail as a document.

• security: an operator session; every tenant credential answers not found
• idempotency: safe read
• response: OperatorAudit (application/json)
• refusals: operator_not_found, unavailable
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.audit.refuse_patch

PATCH /operator/api/audit/{sequence} — refuse an audit edit

Every attempt to edit an audit entry is refused and itself audited.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• path: sequence
• response: AuditRefusal (application/json)
• refusals: operator_not_found, unavailable, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

operator.audit.refuse_delete

DELETE /operator/api/audit/{sequence} — refuse an audit deletion

Every attempt to delete an audit entry is refused and itself audited.

• security: an operator session; every tenant credential answers not found
• idempotency: operator mutation; audited, not keyed
• path: sequence
• response: AuditRefusal (application/json)
• refusals: operator_not_found, unavailable, conflict
• cli: none: operator operations are performed under the operator identity, not by tenant credentials

schemas

The component schemas are in the served document under components.schemas; each operation names its body and response schema above.